From 8d58b5f5e77f2dcc6631d69da5835b3c6ecf116e Mon Sep 17 00:00:00 2001 From: Akula Uday Date: Fri, 12 Jun 2026 14:39:56 +0530 Subject: [PATCH] fix(ai-transformation): development-ai-transformation --- .claude/agents/cross-verifier.md | 100 ++++ .claude/agents/dev-implementer.md | 101 ++++ .claude/agents/planner.md | 92 +++ .claude/agents/post-merge.md | 87 +++ .claude/commands/dev-implement.md | 69 +++ .claude/commands/dev-post-merge.md | 55 ++ .claude/commands/dev-pr.md | 63 +++ .claude/commands/dev-review.md | 46 ++ .claude/commands/dev-start.md | 71 +++ .claude/commands/dev-verify.md | 54 ++ .cursor/rules/development-phase.mdc | 26 + AGENTS.md | 12 +- CLAUDE.md | 19 + ai-docs/harness/development-phase-plan.md | 527 ++++++++++++++++++ ai-docs/harness/guardrails-pr-tdd.md | 146 +++++ ai-docs/templates/README.md | 25 +- .../templates/development-phase/00-master.md | 110 ++++ .../templates/development-phase/01-intake.md | 98 ++++ .../development-phase/02-implementation.md | 92 +++ .../development-phase/03-verification.md | 81 +++ .../development-phase/04-pr-and-review.md | 89 +++ .../development-phase/05-post-merge.md | 97 ++++ .../microservices-delta.md.template | 106 ++++ .../development-phase/spec.md.template | 118 ++++ 24 files changed, 2281 insertions(+), 3 deletions(-) create mode 100644 .claude/agents/cross-verifier.md create mode 100644 .claude/agents/dev-implementer.md create mode 100644 .claude/agents/planner.md create mode 100644 .claude/agents/post-merge.md create mode 100644 .claude/commands/dev-implement.md create mode 100644 .claude/commands/dev-post-merge.md create mode 100644 .claude/commands/dev-pr.md create mode 100644 .claude/commands/dev-review.md create mode 100644 .claude/commands/dev-start.md create mode 100644 .claude/commands/dev-verify.md create mode 100644 .cursor/rules/development-phase.mdc create mode 100644 ai-docs/harness/development-phase-plan.md create mode 100644 ai-docs/harness/guardrails-pr-tdd.md create mode 100644 ai-docs/templates/development-phase/00-master.md create mode 100644 ai-docs/templates/development-phase/01-intake.md create mode 100644 ai-docs/templates/development-phase/02-implementation.md create mode 100644 ai-docs/templates/development-phase/03-verification.md create mode 100644 ai-docs/templates/development-phase/04-pr-and-review.md create mode 100644 ai-docs/templates/development-phase/05-post-merge.md create mode 100644 ai-docs/templates/development-phase/microservices-delta.md.template create mode 100644 ai-docs/templates/development-phase/spec.md.template diff --git a/.claude/agents/cross-verifier.md b/.claude/agents/cross-verifier.md new file mode 100644 index 000000000..a7aaa2eb5 --- /dev/null +++ b/.claude/agents/cross-verifier.md @@ -0,0 +1,100 @@ +--- +name: cross-verifier +description: "Independent code review for Development phase. Compares diff against spec.md and ai-docs patterns. Reviewer only — no implementation." +model: sonnet +color: purple +memory: project +--- + +You are a Cross-Verification agent. You review staged or branch changes against the ticket spec and repository patterns. You do NOT implement fixes. + +## Important: Tool Limitations + +- You do NOT have access to MCP tools. +- You do NOT have access to the Skill tool. +- Return structured JSON — parent decides whether to proceed to PR. + +## Required Context + +- `TICKET_ID`, `WORKTREE_PATH` +- **spec.md** and **plan.md** content +- **git diff** — provided by parent or run read-only: + +```bash +cd {WORKTREE_PATH} +git diff --cached +git diff --cached --stat +``` + +## Review Checklist + +Follow [ai-docs/templates/development-phase/04-pr-and-review.md](ai-docs/templates/development-phase/04-pr-and-review.md). + +### Spec Compliance + +- [ ] Every acceptance criterion in spec.md addressed in diff +- [ ] Spec delta (Added/Updated/Removed) reflected accurately +- [ ] No scope creep beyond plan.md + +### Architecture + +- [ ] Dependency flow: cc-widgets → widgets → cc-components → store → SDK +- [ ] No direct SDK imports in widgets +- [ ] MobX patterns correct +- [ ] No PII/credentials in logs + +### TDD Guardrail + +If diff touches `packages/**/src/**`: + +- [ ] At least one test file in diff under `tests/` or `playwright/` +- Exception: document if docs-only — flag for human waiver + +### PR Size (Advisory) + +- Lines changed ≤ 400, files ≤ 15 (see ai-docs/harness/guardrails-pr-tdd.md) +- If exceeded → add blocker or recommend split + +### ai-docs + +- [ ] If API changed, ai-docs updated consistently +- [ ] Flag spec drift if code and docs mismatch + +## Severity + +- **blocker** — must fix before PR +- **suggestion** — optional improvement +- **specDrift** — documentation inconsistency + +## Return JSON + +```json +{ + "ticketId": "CAI-XXXX", + "status": "success", + "approved": true, + "blockers": [ + { + "severity": "blocker", + "file": "path", + "message": "Missing unit test for new callback" + } + ], + "suggestions": [], + "specDriftFlags": [], + "prSize": { + "lines": 120, + "files": 4, + "withinLimits": true + }, + "error": null +} +``` + +Set `approved: false` if any blocker exists. + +## Safety Rules + +- Do NOT modify code +- Do NOT approve security-sensitive changes without noting human review required +- Do NOT call MCP or create PR diff --git a/.claude/agents/dev-implementer.md b/.claude/agents/dev-implementer.md new file mode 100644 index 000000000..5be63ee79 --- /dev/null +++ b/.claude/agents/dev-implementer.md @@ -0,0 +1,101 @@ +--- +name: dev-implementer +description: "TDD implementation for Development phase harness. Writes failing tests first, implements per spec.md and plan.md, verifies unit tests, updates ai-docs if API changed. Stages changes only." +model: sonnet +color: green +memory: project +--- + +You are a Development Implementation agent. You implement features and fixes per `spec.md` and `plan.md` using TDD. The parent handles Jira, PR, and MCP. + +## Important: Tool Limitations + +- You do NOT have access to MCP tools (Jira, Playwright, etc.). +- You do NOT have access to the Skill tool. TDD methodology is embedded below. +- You do NOT have access to `gh` CLI. +- Return structured JSON — parent handles Jira comments and PR. + +## Required Context + +- `TICKET_ID`, `WORKTREE_PATH`, `REPO_ROOT` +- **spec.md** and **plan.md** content (pre-fetched or read from worktree) +- **taskType** — A/B/C/F for template routing + +**ALL file operations MUST use absolute paths under WORKTREE_PATH.** + +## Workflow + +Follow [ai-docs/templates/development-phase/02-implementation.md](ai-docs/templates/development-phase/02-implementation.md). + +### 1. Read Documentation + +- `{WORKTREE_PATH}/spec.md`, `{WORKTREE_PATH}/plan.md` +- Scope package `ai-docs/AGENTS.md` and `ARCHITECTURE.md` +- `{WORKTREE_PATH}/AGENTS.md`, relevant `ai-docs/patterns/` + +### 2. Route to Template (guidance) + +| taskType | Template | +|----------|----------| +| A | ai-docs/templates/new-widget/ | +| B | ai-docs/templates/existing-widget/bug-fix.md | +| C | ai-docs/templates/existing-widget/feature-enhancement.md | +| F | ai-docs/templates/playwright/ | + +### 3. TDD — For Each Acceptance Criterion + +1. Write failing test (Jest + RTL under `packages/**/tests/`) +2. Run `yarn workspace @webex/{pkg} test:unit` — confirm failure +3. Implement minimal code (Widget → Hook → Component → Store → SDK) +4. Re-run until green + +### 4. Architecture Rules + +- SDK only via `store.cc.methodName()` +- `observer()` on widgets; `runInAction()` for MobX +- No `@webex/cc-widgets` imports in widget packages +- ErrorBoundary + withMetrics on exports +- No `any`; no PII in logs + +### 5. ai-docs Updates + +If public API changed, update scope `ai-docs/AGENTS.md` / `ARCHITECTURE.md`. + +### 6. Verify and Stage + +```bash +cd {WORKTREE_PATH} +yarn workspace @webex/{SCOPE} test:unit +git add -A +git diff --cached --stat +``` + +**STOP if tests fail.** Return `status: "failed"`. + +## Exit Conditions + +- All planned unit tests pass +- Changes staged (or list unstaged paths in JSON if staging failed) +- ai-docs updated if needed + +## Return JSON + +```json +{ + "ticketId": "CAI-XXXX", + "status": "success|failed", + "testsAdded": ["packages/.../tests/..."], + "testsPassing": true, + "filesChanged": ["packages/.../src/..."], + "aiDocsUpdated": false, + "staged": true, + "error": null +} +``` + +## Safety Rules + +- NEVER skip failing-test-first for production code changes +- NEVER commit or push +- NEVER call MCP +- If plan and spec conflict, document in `error` and stop diff --git a/.claude/agents/planner.md b/.claude/agents/planner.md new file mode 100644 index 000000000..fb5821abe --- /dev/null +++ b/.claude/agents/planner.md @@ -0,0 +1,92 @@ +--- +name: planner +description: "Turn spec.md and scope ai-docs into an implementation plan: files to touch, test strategy, risks. Returns structured JSON; parent posts plan to Jira." +model: sonnet +color: blue +memory: project +--- + +You are a Planner agent for the Development phase harness. You produce an implementation plan from a normalized ticket spec — you do NOT write production code. + +## Important: Tool Limitations + +- You do NOT have access to MCP tools (Jira, Playwright, etc.). +- You do NOT have access to the Skill tool. Planning methodology is embedded below. +- All ticket context is provided in your prompt by the parent agent. +- Return structured JSON — the parent posts to Jira and spawns the Implementation agent. + +## Required Context + +You will receive: + +- `TICKET_ID` — JIRA key (e.g., CAI-7359) +- `WORKTREE_PATH` — absolute path (e.g., /tmp/claude-widgets/CAI-7359) +- `REPO_ROOT` — main repository path +- **spec.md content** — pre-fetched by parent +- **Scope ai-docs paths** — package AGENTS.md / ARCHITECTURE.md to read + +**ALL file operations MUST use absolute paths under WORKTREE_PATH.** + +## Workflow + +### 1. Read Inputs + +Read from worktree: + +- `{WORKTREE_PATH}/spec.md` +- Scope `{WORKTREE_PATH}/packages/.../ai-docs/AGENTS.md` and `ARCHITECTURE.md` +- `{WORKTREE_PATH}/AGENTS.md` for architecture rules +- Relevant `{WORKTREE_PATH}/ai-docs/patterns/` as needed + +### 2. SDK Verification + +If spec references SDK methods, verify names against `contact-centre-sdk-apis/contact-center.json` (if present in worktree). Flag unknown methods in `risks[]`. + +### 3. Produce Plan + +Write `{WORKTREE_PATH}/plan.md` with: + +- Files to create/modify (concrete paths) +- Layer mapping: Widget → Hook → Component → Store → SDK +- Unit test strategy (file paths, scenarios) +- E2E strategy (Playwright SET/file or N/A with reason) +- Risks and mitigations +- Ticket split recommendation if scope exceeds PR size guardrails (400 lines / 15 files) + +### 4. Task Type Routing + +Note which AGENTS.md template applies (A/B/C/F) for the Implementation agent. + +## Exit Conditions + +- `plan.md` written in worktree +- JSON result returned to parent +- If spec is ambiguous → list `blockers[]` in JSON; do not invent requirements + +## Return JSON + +```json +{ + "ticketId": "CAI-XXXX", + "status": "success|blocked", + "planPath": "/tmp/claude-widgets/CAI-XXXX/plan.md", + "planSummary": "One-line summary", + "filesToTouch": ["packages/..."], + "testStrategy": { + "unit": ["packages/.../tests/..."], + "e2e": ["playwright/tests/..."] + }, + "taskType": "A|B|C|F", + "risks": [], + "blockers": [], + "humanApprovalRequired": false, + "recommendTicketSplit": false, + "error": null +} +``` + +## Safety Rules + +- Do NOT implement code or write tests — planning only +- Do NOT call MCP or gh +- Do NOT skip reading scope ai-docs when path is provided diff --git a/.claude/agents/post-merge.md b/.claude/agents/post-merge.md new file mode 100644 index 000000000..b6e1ededa --- /dev/null +++ b/.claude/agents/post-merge.md @@ -0,0 +1,87 @@ +--- +name: post-merge +description: "Generate post-merge artifacts for Development phase: usage spec, microservices-delta.md, troubleshooting updates. Returns JSON with artifact paths; parent posts to Jira and triggers Security workflow." +model: sonnet +color: cyan +memory: project +--- + +You are a Post-Merge agent. After a PR merges, you generate handoff artifacts for Security, Beta, and GTM phases. + +## Important: Tool Limitations + +- You do NOT have access to MCP tools. +- You do NOT have access to the Skill tool. +- Parent posts artifacts to Jira and triggers external Security webhook. + +## Required Context + +- `TICKET_ID`, `WORKTREE_PATH` (or main repo path post-merge) +- **Merged PR diff summary** — provided by parent +- **spec.md** content +- **PR URL** and merge SHA + +## Workflow + +Follow [ai-docs/templates/development-phase/05-post-merge.md](ai-docs/templates/development-phase/05-post-merge.md). + +### 1. Usage SPEC + +Generate markdown usage documentation: + +- New/changed public API (props, callbacks, exports) +- Usage examples +- Reference [ai-docs/templates/documentation/create-agent-md.md](ai-docs/templates/documentation/create-agent-md.md) + +Write to: `{WORKTREE_PATH}/artifacts/{TICKET_ID}-usage-spec.md` + +### 2. microservices-delta.md + +Copy [ai-docs/templates/development-phase/microservices-delta.md.template](ai-docs/templates/development-phase/microservices-delta.md.template) and fill: + +- API surface changes +- Dependencies / TPS +- Security considerations +- Data flow + +Write to: `{WORKTREE_PATH}/artifacts/{TICKET_ID}-microservices-delta.md` + +### 3. Troubleshooting Delta + +Produce append-only markdown for ARCHITECTURE.md § Troubleshooting: + +- New failure modes +- Diagnostic steps + +Write to: `{WORKTREE_PATH}/artifacts/{TICKET_ID}-troubleshooting.md` + +### 4. Stage Artifacts + +```bash +mkdir -p {WORKTREE_PATH}/artifacts +# write files +git add artifacts/ # if in worktree; else parent handles +``` + +## Return JSON + +```json +{ + "ticketId": "CAI-XXXX", + "status": "success|failed", + "artifacts": { + "usageSpec": "/path/to/usage-spec.md", + "microservicesDelta": "/path/to/microservices-delta.md", + "troubleshootingGuide": "/path/to/troubleshooting.md" + }, + "securityWorkflowRecommended": true, + "summary": "One-line for Jira comment", + "error": null +} +``` + +## Safety Rules + +- Do NOT publish to ContentStack, Tech Zone, or Corona — parent/org pipeline only +- Do NOT include secrets or PII in artifacts +- Base security claims on actual diff evidence only diff --git a/.claude/commands/dev-implement.md b/.claude/commands/dev-implement.md new file mode 100644 index 000000000..efdfe5882 --- /dev/null +++ b/.claude/commands/dev-implement.md @@ -0,0 +1,69 @@ +# Dev Implement Command + +## Description + +TDD implementation phase for a Development harness ticket. Spawns **dev-implementer** subagent. + +## Arguments + +- Required: ticket ID (e.g., `/dev-implement CAI-1234`) + +## Prerequisites + +- `/dev-start` completed (worktree, spec.md, plan.md exist) +- Label `dev-in-progress` + +## Skills Integration + +| Skill | When | Purpose | +|-------|------|---------| +| `superpowers:test-driven-development` | Before spawn | Failing test first | +| `superpowers:systematic-debugging` | Bug taskType B | Root cause before fix | + +## Workflow + +### Step 1: Validate Worktree + +```bash +test -d /tmp/claude-widgets/{TICKET_ID} || echo "NOT_FOUND" +test -f /tmp/claude-widgets/{TICKET_ID}/spec.md +test -f /tmp/claude-widgets/{TICKET_ID}/plan.md +``` + +### Step 2: Prefetch Context + +Read spec.md, plan.md, latest Jira intake/plan comments. + +Determine `taskType` and `scopePackages` from intake JSON. + +### Step 3: Spawn Dev Implementer + +Agent: `.claude/agents/dev-implementer.md` + +Pass all context as structured text (no raw Jira MCP in subagent). + +### Step 4: Verify Tests (Parent) + +```bash +cd /tmp/claude-widgets/{TICKET_ID} +yarn workspace @webex/{SCOPE} test:unit +``` + +### Step 5: Stage Fallback + +If subagent could not stage: + +```bash +cd /tmp/claude-widgets/{TICKET_ID} +git add -A +``` + +### Step 6: Jira Comment + +Post implementation JSON from subagent result. + +On failure → do not proceed to `/dev-verify`. + +## Reference + +[02-implementation.md](../../ai-docs/templates/development-phase/02-implementation.md) diff --git a/.claude/commands/dev-post-merge.md b/.claude/commands/dev-post-merge.md new file mode 100644 index 000000000..b5d306811 --- /dev/null +++ b/.claude/commands/dev-post-merge.md @@ -0,0 +1,55 @@ +# Dev Post-Merge Command + +## Description + +Generate post-merge artifacts after PR merge: usage spec, microservices-delta.md, troubleshooting delta. + +## Arguments + +- Required: ticket ID (e.g., `/dev-post-merge CAI-1234`) + +## Prerequisites + +- PR merged to `next` +- Label `dev-merged` (apply if not present) + +## Workflow + +### Step 1: Gather Merge Context + +```bash +# PR diff vs next (adjust branch as needed) +gh pr view {PR_NUMBER} --json url,mergeCommit,files +``` + +Read spec.md from worktree or Jira attachment. + +### Step 2: Spawn Post-Merge Agent + +Agent: `.claude/agents/post-merge.md` + +Pass: TICKET_ID, PR URL, merge SHA, diff summary, spec.md. + +### Step 3: Jira Updates + +- Label ticket `dev-merged` +- Label Security epic ticket `sec-input-ready` +- Post post-merge JSON comment with artifact paths + +``` +mcp__jira__add_labels(issueKey="{TICKET_ID}", labels=["dev-merged"]) +``` + +### Step 4: Security Workflow (Manual/Webhook) + +Trigger org Security AI workflow if webhook URL configured — document in team runbook. + +Parent does NOT implement Corona/Lambda — interface only. + +### Step 5: Handoff + +Notify Beta/GTM teams with artifact links per org process. + +## Reference + +[05-post-merge.md](../../ai-docs/templates/development-phase/05-post-merge.md) diff --git a/.claude/commands/dev-pr.md b/.claude/commands/dev-pr.md new file mode 100644 index 000000000..f68c2bf34 --- /dev/null +++ b/.claude/commands/dev-pr.md @@ -0,0 +1,63 @@ +# Dev PR Command + +## Description + +Cross-verification + draft PR creation for Development harness ticket. + +Combines review gate and PR submission. Main conversation may spawn **cross-verifier** then **git-pr**, or run verification steps directly. + +## Arguments + +- Required: ticket ID (e.g., `/dev-pr CAI-1234`) + +## Prerequisites + +- `/dev-verify` passed +- Staged changes in worktree + +## Skills Integration + +| Skill | When | Purpose | +|-------|------|---------| +| `superpowers:requesting-code-review` | Before PR | Self/cross review | +| `superpowers:verification-before-completion` | Pre-commit | Final check | +| `superpowers:finishing-a-development-branch` | After PR | Branch hygiene | + +## Workflow + +### Step 1: Cross-Verification + +Spawn `.claude/agents/cross-verifier.md` with diff + spec.md. + +If `approved: false` → STOP; fix via `/dev-implement`. + +### Step 2: Guardrails + +Apply [guardrails-pr-tdd.md](../../ai-docs/harness/guardrails-pr-tdd.md) checklist (PR size, TDD-in-diff). + +### Step 3: Confirm with User + +AskUserQuestion before PR creation (reuse `/submit-pr` pattern). + +### Step 4: Create PR + +Option A: Spawn `.claude/agents/git-pr.md` + +Option B: Run `/submit-pr {TICKET_ID}` workflow in main conversation + +### Step 5: Jira + +- Label `dev-pr-open` +- Post PR JSON comment + +``` +mcp__jira__add_labels(issueKey="{TICKET_ID}", labels=["dev-pr-open"]) +``` + +### Step 6: CI Labels + +Remind human to add PR labels `validated` and `run_e2e` if applicable. + +## Reference + +[04-pr-and-review.md](../../ai-docs/templates/development-phase/04-pr-and-review.md) diff --git a/.claude/commands/dev-review.md b/.claude/commands/dev-review.md new file mode 100644 index 000000000..19adfb61b --- /dev/null +++ b/.claude/commands/dev-review.md @@ -0,0 +1,46 @@ +# Dev Review Command + +## Description + +Standalone cross-verification review without PR creation. Use before `/dev-pr` or after implementation changes. + +## Arguments + +- Required: ticket ID (e.g., `/dev-review CAI-1234`) + +## Skills Integration + +| Skill | When | Purpose | +|-------|------|---------| +| `superpowers:requesting-code-review` | Review spawn | Structured review | + +## Workflow + +### Step 1: Gather Diff + +```bash +cd /tmp/claude-widgets/{TICKET_ID} +git diff --cached --stat +git diff --cached +``` + +### Step 2: Spawn Cross-Verifier + +Agent: `.claude/agents/cross-verifier.md` + +Pass: spec.md, plan.md, diff, scope ai-docs paths. + +### Step 3: Report + +Display blockers and suggestions to user. + +Post review JSON to Jira comment. + +### Step 4: Next Step + +- If approved → `/dev-pr {TICKET_ID}` +- If blockers → `/dev-implement {TICKET_ID}` + +## Reference + +[04-pr-and-review.md](../../ai-docs/templates/development-phase/04-pr-and-review.md) diff --git a/.claude/commands/dev-start.md b/.claude/commands/dev-start.md new file mode 100644 index 000000000..d39b1787d --- /dev/null +++ b/.claude/commands/dev-start.md @@ -0,0 +1,71 @@ +# Dev Start Command + +## Description + +Start Development phase for a Jira ticket: intake gate, worktree setup, spec.md generation, and planning. + +**Runs in main conversation** for Jira MCP and worktree setup. Spawns **planner** subagent after intake passes. + +## Arguments + +- Required: ticket ID (e.g., `/dev-start CAI-1234`) + +## Skills Integration + +| Skill | When | Purpose | +|-------|------|---------| +| `superpowers:using-git-worktrees` | Worktree creation | Isolated implementation | +| `superpowers:writing-plans` | Before planner spawn | Plan quality gate | + +## Workflow + +### Step 1: Fetch Jira Ticket + +``` +mcp__jira__call_jira_rest_api(endpoint="/issue/{TICKET_ID}", method="GET") +``` + +Fetch linked epic, DoR links, and Discovery comments. + +### Step 2: Intake Gate + +Follow [ai-docs/templates/development-phase/01-intake.md](../../ai-docs/templates/development-phase/01-intake.md). + +If blockers → post Jira comment; STOP. + +### Step 3: Worktree + +```bash +git worktree add /tmp/claude-widgets/{TICKET_ID} -b {TICKET_ID} +cd /tmp/claude-widgets/{TICKET_ID} +yarn install && yarn build:dev +``` + +### Step 4: Generate spec.md + +Copy [spec.md.template](../../ai-docs/templates/development-phase/spec.md.template) → `spec.md`; fill from DoR + ticket. + +### Step 5: Jira Update + +- Add label `dev-ready` then `dev-in-progress` +- Post intake JSON comment (see [development-phase-plan.md](../../ai-docs/harness/development-phase-plan.md) §8.2) + +``` +mcp__jira__add_labels(issueKey="{TICKET_ID}", labels=["dev-ready", "dev-in-progress"]) +``` + +### Step 6: Spawn Planner Agent + +Pass: TICKET_ID, WORKTREE_PATH, REPO_ROOT, spec.md content, scope ai-docs paths. + +Agent: `.claude/agents/planner.md` + +### Step 7: Post Plan to Jira + +On planner success → post plan JSON comment with planSummary and filesToTouch. + +If `humanApprovalRequired: true` → AskUserQuestion before `/dev-implement`. + +## Reference + +[development-phase-plan.md](../../ai-docs/harness/development-phase-plan.md) diff --git a/.claude/commands/dev-verify.md b/.claude/commands/dev-verify.md new file mode 100644 index 000000000..617b10787 --- /dev/null +++ b/.claude/commands/dev-verify.md @@ -0,0 +1,54 @@ +# Dev Verify Command + +## Description + +Verification phase: build, lint, E2E. Parent runs commands; may spawn E2E-focused subagent for Playwright test authoring. + +## Arguments + +- Required: ticket ID (e.g., `/dev-verify CAI-1234`) + +## Skills Integration + +| Skill | When | Purpose | +|-------|------|---------| +| `superpowers:verification-before-completion` | Before PR path | Evidence before assertions | + +## Workflow + +### Step 1: Unit + Build + +```bash +cd /tmp/claude-widgets/{TICKET_ID} +yarn build:dev +yarn workspace @webex/{SCOPE} test:unit +yarn workspace @webex/{SCOPE} test:styles +``` + +STOP on failure → return to `/dev-implement`. + +### Step 2: E2E (If Required per spec.md) + +If test plan requires E2E: + +1. Spawn subagent with playwright template guidance to add/update tests +2. Parent runs: + +```bash +yarn test:e2e +# or targeted suite +``` + +Document waiver in Jira if skipped with human approval. + +### Step 3: Spec Drift (If ai-docs Changed) + +Run `/spec-drift-changed` if implementation updated ai-docs. + +### Step 4: Proceed + +On success → suggest `/dev-review {TICKET_ID}`. + +## Reference + +[03-verification.md](../../ai-docs/templates/development-phase/03-verification.md) diff --git a/.cursor/rules/development-phase.mdc b/.cursor/rules/development-phase.mdc new file mode 100644 index 000000000..9d94a3c8c --- /dev/null +++ b/.cursor/rules/development-phase.mdc @@ -0,0 +1,26 @@ +# Development Phase Harness + +When working on Jira dev tickets from Discovery handoff, follow the Development phase harness. + +## Primary Reference + +- [ai-docs/harness/development-phase-plan.md](../../ai-docs/harness/development-phase-plan.md) + +## Workflow + +1. Complete DoR intake: [01-intake.md](../../ai-docs/templates/development-phase/01-intake.md) +2. Follow phase modules: [00-master.md](../../ai-docs/templates/development-phase/00-master.md) + +## Claude Code Commands + +`/dev-start` → `/dev-implement` → `/dev-verify` → `/dev-review` → `/dev-pr` → (after merge) `/dev-post-merge` + +## Cursor + +- Orchestrator runs in main agent with Jira/GitHub MCP +- Spawn subagents via Task tool: planner, dev-implementer, cross-verifier, git-pr, post-merge +- Parent prefetches Jira; pass JSON to subagents (no raw MCP dumps) + +## Guardrails + +[guardrails-pr-tdd.md](../../ai-docs/harness/guardrails-pr-tdd.md) diff --git a/AGENTS.md b/AGENTS.md index 193649a3c..867402460 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ This is the main orchestrator for AI assistants working on this repository. It routes you to the correct templates and documentation based on the developer's task. -**For every developer request:** (1) Identify task type (A–F below). (2) If the work is in an existing package, widget, or test framework scope, load that scope's ai-docs (see [Package and widget ai-docs reference](#package-and-widget-ai-docs-reference)) and follow its AGENTS.md. (3) Open the template for that type and complete its mandatory pre-steps (see [Mandatory pre-steps by task type](#mandatory-pre-steps-by-task-type)). (4) Then follow the rest of this guide and the template. +**For every developer request:** (1) Identify task type (A–G below). (2) If the work is in an existing package, widget, or test framework scope, load that scope's ai-docs (see [Package and widget ai-docs reference](#package-and-widget-ai-docs-reference)) and follow its AGENTS.md. (3) Open the template for that type and complete its mandatory pre-steps (see [Mandatory pre-steps by task type](#mandatory-pre-steps-by-task-type)). (4) Then follow the rest of this guide and the template. --- @@ -63,6 +63,14 @@ If the developer's message contains multiple distinct task types (for example, " - **Follow:** Playwright template workflow (pre-questions → implementation → validation) - **⚠️ MANDATORY FIRST STEP:** Complete pre-questions in [templates/playwright/01-pre-questions.md](./ai-docs/templates/playwright/01-pre-questions.md) +**G. Development Phase Harness** +- Jira dev ticket handed off from Discovery (DoR complete); full lifecycle from intake through merge and post-merge artifacts +- **Route to:** [harness/development-phase-plan.md](./ai-docs/harness/development-phase-plan.md) +- **Follow:** [templates/development-phase/00-master.md](./ai-docs/templates/development-phase/00-master.md) (intake → plan → implement → verify → PR → post-merge) +- **⚠️ MANDATORY FIRST STEP:** Complete DoR intake gate in [templates/development-phase/01-intake.md](./ai-docs/templates/development-phase/01-intake.md) +- **Claude Code commands:** `/dev-start`, `/dev-implement`, `/dev-verify`, `/dev-review`, `/dev-pr`, `/dev-post-merge` (see [CLAUDE.md](./CLAUDE.md)) +- **Also routes to:** Task types A/B/C/F templates based on `taskType` in intake JSON + --- ## ⚠️ CRITICAL RULES - Always Follow @@ -176,6 +184,7 @@ Before generating or changing any code, you MUST complete the **pre-step section | **D. Documentation only** | documentation templates | Optional: confirm scope with developer (no code change) | | **E. Understanding** | Package ai-docs | None (read-only) | | **F. Playwright E2E Test Work** | [playwright/00-master.md](./ai-docs/templates/playwright/00-master.md) | [Pre-Questions](./ai-docs/templates/playwright/01-pre-questions.md) (scope, scenarios, setup/utilities, stability expectations) | +| **G. Development Phase Harness** | [harness/development-phase-plan.md](./ai-docs/harness/development-phase-plan.md) | [DoR Intake Gate](./ai-docs/templates/development-phase/01-intake.md) (Discovery artifacts, spec.md, Jira epic/ticket readiness) | --- @@ -210,6 +219,7 @@ Before generating or changing any code, you MUST complete the **pre-step section | **ui-logging** | [packages/contact-center/ui-logging/ai-docs/AGENTS.md](packages/contact-center/ui-logging/ai-docs/AGENTS.md) | Same folder | | **samples-cc-react-app** | [widgets-samples/cc/samples-cc-react-app/ai-docs/AGENTS.md](widgets-samples/cc/samples-cc-react-app/ai-docs/AGENTS.md) | Same folder if present | | **playwright framework** | [playwright/ai-docs/AGENTS.md](playwright/ai-docs/AGENTS.md) | [playwright/ai-docs/ARCHITECTURE.md](playwright/ai-docs/ARCHITECTURE.md) | +| **Development phase harness** | [ai-docs/harness/development-phase-plan.md](ai-docs/harness/development-phase-plan.md) | [ai-docs/harness/guardrails-pr-tdd.md](ai-docs/harness/guardrails-pr-tdd.md) | **Task package note:** The task package has multiple widgets (CallControl, IncomingTask, OutdialCall, TaskList). When working on one of them, use that widget's ai-docs path above, not a generic task path. diff --git a/CLAUDE.md b/CLAUDE.md index 5513353ee..df91af656 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -61,6 +61,21 @@ corepack enable # If yarn is unavailable Inter-stage state passes via **Jira comments** (durable, human-visible). Each stage reads previous stage's comments. Jira labels track progress: `scrubbed` → `prioritize`/`followup`/`dolater` → `triaged` → `fixing` → `fixed`. +### Development Phase Harness + +| Command | Stage | Agent | Purpose | +|---------|-------|-------|---------| +| `/dev-start` | Intake + Plan | planner | DoR gate, worktree, spec.md, implementation plan | +| `/dev-implement` | Implement | dev-implementer | TDD implementation per spec.md | +| `/dev-verify` | Verify | parent (+ E2E) | Build, unit tests, Playwright E2E | +| `/dev-review` | Review | cross-verifier | Independent diff review vs spec.md | +| `/dev-pr` | PR | cross-verifier + git-pr | Guardrails + draft PR | +| `/dev-post-merge` | Post-merge | post-merge | Usage spec, microservices-delta, troubleshooting | + +Jira labels: `dev-ready` → `dev-in-progress` → `dev-pr-open` → `dev-merged` → `sec-input-ready` + +Full architecture: [ai-docs/harness/development-phase-plan.md](ai-docs/harness/development-phase-plan.md) + ### Other Commands | Command | Purpose | @@ -68,6 +83,8 @@ Jira labels track progress: `scrubbed` → `prioritize`/`followup`/`dolater` → | `/fix-tickets` | Full lifecycle: fetch Jira tickets → worktree → implement → PR (uses superpowers skills) | | `/submit-pr` | Commit + push + create PR for a worktree. Runs in main conversation (no subagents) | | `/cleanup-worktrees` | List, inspect, and remove worktrees in `/tmp/claude-widgets/` | +| `/spec-drift` | Full ai-docs vs code scan | +| `/spec-drift-changed` | Scoped spec-drift check before commit | ## Subagent Constraints @@ -123,6 +140,8 @@ Invoke these skills at the right workflow stage — they enforce discipline that | Bug fix template | `ai-docs/templates/existing-widget/bug-fix.md` | | Feature enhancement template | `ai-docs/templates/existing-widget/feature-enhancement.md` | | Playwright E2E template (4-step) | `ai-docs/templates/playwright/` | +| Development phase harness | `ai-docs/harness/development-phase-plan.md` | +| Development phase templates | `ai-docs/templates/development-phase/` | | SDK API reference (TypeDoc JSON) | `contact-centre-sdk-apis/contact-center.json` | | Per-package architecture & agent docs | `packages/contact-center/{pkg}/ai-docs/` | diff --git a/ai-docs/harness/development-phase-plan.md b/ai-docs/harness/development-phase-plan.md new file mode 100644 index 000000000..c164cc949 --- /dev/null +++ b/ai-docs/harness/development-phase-plan.md @@ -0,0 +1,527 @@ +# Development Phase Harness Engineering Plan + +Org-wide harness for the **Development phase** of feature delivery. This document is tool-agnostic at the core, with bindings for **Claude Code** and **Cursor**. The widgets repo is the pilot reference implementation; copy this doc and templates to other repos as needed. + +--- + +## 1. Executive Summary + +### 1.1 Purpose + +Define how work enters Development after Discovery, which agents/skills/MCP tools participate, validation and review gates, exit criteria, and handoffs to Security, Beta, and GTM. + +### 1.2 Scope + +| In scope | Out of scope | +|----------|--------------| +| Jira-assigned implementation through merge | Discovery DoR creation | +| Unit tests, E2E tests, PR creation | Security AI pipeline implementation | +| Post-merge artifact triggers | Beta doc publish pipeline | +| Handoff interfaces to downstream phases | GTM ContentStack / Tech Zone automation | + +### 1.3 Workstreams and Team + +- **Workstreams:** WS-2, WS-3, WS-6, WS-9 +- **Phase:** Development (Phase 2 in the GTM lifecycle) +- **Team (GTM board):** Bala, Priya, Uday, Ravi, Ritesh, Vivek, Rajesh, Ashish, Vamshi + +### 1.4 Related Documents + +| Document | Path | +|----------|------| +| Root orchestrator | [AGENTS.md](../../AGENTS.md) — Task type G | +| Claude Code bindings | [CLAUDE.md](../../CLAUDE.md) — `/dev-*` commands | +| Phase templates | [ai-docs/templates/development-phase/](../templates/development-phase/) | +| Agent definitions | [.claude/agents/](../../.claude/agents/) | +| Guardrails (proposed CI) | [ai-docs/harness/guardrails-pr-tdd.md](./guardrails-pr-tdd.md) | + +--- + +## 2. Prerequisites from Discovery (Entry Gate) + +Development MUST NOT start until the orchestrator passes the DoR intake gate ([01-intake.md](../templates/development-phase/01-intake.md)). + +### 2.1 Required Input Artifacts + +| Input artifact | Source phase | Required fields | +|----------------|--------------|-----------------| +| **Feature SPEC** | CAPTURE | Task list, business use cases, acceptance criteria | +| **DoR deck** | Discovery | High/low-level design, API details, error scenarios, limitations, open questions, test plan | +| **Jira Dev Epic + tickets** | Discovery | English description, **Spec delta** (Added / Removed / Updated), component scope, dependencies | +| **Raw data bundle** | CAPTURE | PF/feature desc, OpenAPI/Swagger, design mockup/Figma, CH flags/SKU docs, repo links, dependent Jira | +| **Security Epic stub** | Discovery | Placeholder for post-merge `microservices-delta.md` | +| **Beta Epic stub** | Discovery | Usage spec expectations | + +### 2.2 Normalized Ticket Artifact: `spec.md` + +Each dev ticket gets a **`spec.md`** synthesized from DoR + ticket spec delta. Store in: + +- Worktree: `/tmp/claude-widgets/{TICKET_ID}/spec.md`, or +- Jira attachment / Confluence link referenced in ticket + +Use template: [spec.md.template](../templates/development-phase/spec.md.template) + +### 2.3 Gate Rule + +1. Orchestrator runs DoR checklist. +2. If blockers remain → Jira comment with blocker list; ticket stays in Discovery (`discovery-complete`, not `dev-ready`). +3. If pass → label `dev-ready`; post intake JSON comment; proceed to Phase 0. + +--- + +## 3. Architecture Overview + +```mermaid +flowchart TB + subgraph discovery [Discovery Outputs] + DoR[DoR Deck] + FeatureSpec[Feature SPEC] + JiraEpic[Jira Dev Epic plus Tickets] + end + + subgraph orchestrator [Orchestrator Parent Agent] + IntakeGate[DoR Intake Gate] + MCPRouter[MCP Tool Router] + Handoff[Agent Handoff Controller] + end + + subgraph devAgents [Development Subagents] + Planner[Planner Agent] + Implementer[Implementation Agent TDD] + E2EAgent[E2E Agent] + Reviewer[Cross Verification Agent] + GitPR[Git PR Agent] + end + + subgraph validation [Validation Gates] + UT[Unit Tests] + E2E[E2E Tests Playwright] + Build[Build plus Lint] + Guardrails[PR Size TDD Spec Drift] + Human[Human Review] + end + + subgraph postMerge [Post Merge Artifacts] + UsageSpec[Usage SPEC] + DeltaMd[microservices delta.md] + Troubleshoot[Troubleshooting Guide] + SecTrigger[Security AI Workflow Trigger] + end + + discovery --> IntakeGate + IntakeGate -->|pass| MCPRouter + MCPRouter --> Planner + Planner --> Implementer + Implementer --> UT + UT -->|fail| Implementer + UT -->|pass| E2EAgent + E2EAgent --> E2E + E2E -->|fail| Implementer + E2E -->|pass| Reviewer + Reviewer --> GitPR + GitPR --> Guardrails + Guardrails --> Human + Human -->|merge| postMerge +``` + +### 3.1 Parent vs Subagent Split (Non-Negotiable) + +| Role | MCP / gh / Playwright? | Responsibilities | +|------|------------------------|------------------| +| **Orchestrator (parent)** | Yes | Jira fetch/update, worktree creation, MCP routing, prefetch external context, spawn subagents, post Jira comments, trigger post-merge workflows | +| **Subagents** | No | Operate in isolated worktree; return structured JSON; stage files only | + +This mitigates TPS challenges: context poisoning, agent handoff, MCP tool flooding. + +### 3.2 MCP Tool Router + +Only load tools needed per phase. Max **3 MCP servers** active per orchestrator turn. + +| Phase | Primary MCP | Optional MCP | CLI fallback | +|-------|-------------|--------------|--------------| +| Intake | Jira | Confluence | — | +| Planning | Jira, Confluence | Figma | — | +| Implementation | GitHub (read) | dev-tools | `gh` read-only | +| E2E | Playwright | — | `yarn test:e2e` | +| PR | GitHub, Jira | — | `gh pr create` | +| Post-merge | Jira | Confluence | Security webhook | + +**Router rules:** + +1. Read MCP tool schema/descriptor before every call. +2. Never pass raw MCP dumps into subagent prompts — parent summarizes to structured JSON. +3. Batch Jira fetches in parent to reduce rate-limit hits. + +--- + +## 4. Agent Roster + +Each agent: fixed persona in `.claude/agents/` (Claude Code) or Task `subagent_type` (Cursor). + +### 4.1 Orchestrator Agent + +| Field | Value | +|-------|-------| +| **Goal** | Route Discovery handoff through Development lifecycle | +| **Persona** | Project manager + integration; no direct code edits unless unblocking | +| **Inputs** | Jira ticket, DoR artifacts, Feature SPEC | +| **Outputs** | Jira labels/comments, spawned subagents, worktree path | +| **Tools** | Jira MCP, GitHub MCP, Confluence MCP (phase-dependent) | +| **Exit** | All epic tickets reach `dev-merged` OR escalated to human | +| **Handoff to** | Planner → Implementer → E2E → Reviewer → Git PR → Post-merge | + +### 4.2 Planner Agent + +| Field | Value | +|-------|-------| +| **Goal** | Turn `spec.md` + scope ai-docs into implementation plan | +| **Inputs** | `spec.md`, package `ai-docs/AGENTS.md`, SDK KB | +| **Outputs** | `plan.md` as Jira comment; optional ticket split | +| **Tools** | None (read-only in worktree) | +| **Exit** | Plan posted; human approved OR DoR marked auto-approved | +| **Handoff to** | Implementation Agent | +| **Model** | Reasoning-capable (sonnet/opus class) | +| **Agent file** | [.claude/agents/planner.md](../../.claude/agents/planner.md) | + +### 4.3 Implementation Agent (Dev Implementer) + +| Field | Value | +|-------|-------| +| **Goal** | TDD implementation per `spec.md` and `plan.md` | +| **Inputs** | `spec.md`, `plan.md`, scope ai-docs, patterns | +| **Outputs** | Staged code + tests; JSON result | +| **Workflow** | Failing UT → implement → verify UTs → update ai-docs if API changed | +| **Exit** | All unit tests pass; changes staged | +| **Handoff to** | E2E Agent or Cross-Verifier if E2E N/A | +| **Agent file** | [.claude/agents/dev-implementer.md](../../.claude/agents/dev-implementer.md) | + +Extends patterns from [fixer.md](../../.claude/agents/fixer.md) and [AGENTS.md](../../AGENTS.md) Steps 4–5.5. + +### 4.4 E2E Agent + +| Field | Value | +|-------|-------| +| **Goal** | Implement/update Playwright tests per `spec.md` test plan | +| **Inputs** | `spec.md`, [playwright/ai-docs/AGENTS.md](../../playwright/ai-docs/AGENTS.md) | +| **Outputs** | Staged Playwright tests; JSON result | +| **Runs tests** | Parent executes `yarn test:e2e` (subagent writes tests only) | +| **Exit** | E2E pass OR documented skip with human approval | +| **Note** | CI E2E requires PR label `run_e2e` | + +### 4.5 Cross-Verification Agent + +| Field | Value | +|-------|-------| +| **Goal** | Independent review of diff vs `spec.md` and ai-docs patterns | +| **Persona** | Reviewer only — no implementation | +| **Inputs** | `git diff`, `spec.md`, plan, scope ai-docs | +| **Outputs** | Review JSON (blockers, suggestions, spec drift flags) | +| **Exit** | Zero blockers OR human override | +| **Skill** | `superpowers:requesting-code-review` | +| **Agent file** | [.claude/agents/cross-verifier.md](../../.claude/agents/cross-verifier.md) | + +### 4.6 Git PR Agent + +| Field | Value | +|-------|-------| +| **Goal** | Commit, push, draft PR with FedRAMP template | +| **Outputs** | PR URL; Jira label `dev-pr-open` | +| **Base branch** | `next` | +| **Agent file** | [.claude/agents/git-pr.md](../../.claude/agents/git-pr.md) | + +### 4.7 QA Test Coverage Agent (Optional) + +| Field | Value | +|-------|-------| +| **Goal** | Advisory coverage assessment on touched files | +| **When** | New feature or low coverage | +| **Blocking** | No — advisory PR comment only | +| **Agent file** | [.claude/agents/qa-test-coverage.md](../../.claude/agents/qa-test-coverage.md) | + +### 4.8 Post-Merge Agent + +| Field | Value | +|-------|-------| +| **Goal** | Generate downstream artifacts after merge | +| **Outputs** | Usage SPEC, `microservices-delta.md`, troubleshooting updates, Security trigger | +| **Agent file** | [.claude/agents/post-merge.md](../../.claude/agents/post-merge.md) | + +--- + +## 5. Skills Matrix (Commands vs Skills) + +Commands are thin wrappers; skills hold methodology. Subagents embed skill instructions (no Skill tool in subagents). + +| Harness command | Skill(s) | When | +|-----------------|----------|------| +| `/dev-start` | `writing-plans`, ai-docs load | After DoR gate pass | +| `/dev-implement` | `test-driven-development`, `systematic-debugging` | Per Jira ticket | +| `/dev-verify` | `verification-before-completion` | Pre-PR | +| `/dev-pr` | `finishing-a-development-branch` | PR creation | +| `/dev-review` | `requesting-code-review`, `receiving-code-review` | Cross-agent + human | +| Worktree setup | `using-git-worktrees` | `/tmp/claude-widgets/{TICKET_ID}` | + +--- + +## 6. Phase-by-Phase Runbook + +Detailed steps in [00-master.md](../templates/development-phase/00-master.md). + +### Phase 0 — Intake (Discovery → Development) + +1. Fetch Jira ticket + linked DoR/Feature SPEC. +2. Run [01-intake.md](../templates/development-phase/01-intake.md). +3. Generate `spec.md` from template. +4. Label `dev-ready`; post intake JSON comment. +5. Create worktree; `yarn install` + `yarn build:dev`. + +### Phase 1 — Plan + +1. Spawn Planner Agent. +2. Human checkpoint on complex tickets (optional). +3. Post `plan.md` to Jira; label `dev-in-progress`. + +### Phase 2 — Implement (TDD Loop) + +1. Implementation Agent: failing tests first. +2. `yarn workspace @webex/{pkg} test:unit` until green. +3. Spec-drift check if ai-docs/API changed (`/spec-drift-changed`). + +See [02-implementation.md](../templates/development-phase/02-implementation.md). + +### Phase 3 — E2E + +1. E2E Agent updates Playwright per test plan. +2. Parent runs `yarn test:e2e`; add `run_e2e` label on PR when needed. +3. On failure → loop to Phase 2 with failure context. + +See [03-verification.md](../templates/development-phase/03-verification.md). + +### Phase 4 — PR and Review + +1. Cross-Verification Agent reviews diff vs `spec.md`. +2. Git PR Agent creates draft PR. +3. Automated guardrails (see [guardrails-pr-tdd.md](./guardrails-pr-tdd.md)). +4. Human review required before merge. +5. On merge: `dev-pr-open` → `dev-merged`. + +See [04-pr-and-review.md](../templates/development-phase/04-pr-and-review.md). + +### Phase 5 — Post-Merge Artifacts + +| Artifact | Consumer | Template | +|----------|----------|----------| +| Usage SPEC | Beta Docs | [create-agent-md.md](../templates/documentation/create-agent-md.md) | +| `microservices-delta.md` | Security | [microservices-delta.md.template](../templates/development-phase/microservices-delta.md.template) | +| Troubleshooting guide | TAC TOI / GTM | ARCHITECTURE.md § Troubleshooting | +| Security AI workflow | Security phase | Webhook/Lambda (interface only) | + +See [05-post-merge.md](../templates/development-phase/05-post-merge.md). + +Label Security Epic tickets `sec-input-ready`. + +--- + +## 7. Validation and Review Layers + +| Layer | Gate | Owner | +|-------|------|-------| +| 1 | DoR completeness | Orchestrator | +| 2 | Plan review | Planner + human (complex) | +| 3 | TDD — test before code | Implementation Agent | +| 4 | Unit tests green | Implementation Agent + Husky | +| 5 | Architecture (SDK/store/event/UI/import/build) | [AGENTS.md Step 5.5](../../AGENTS.md) | +| 6 | E2E from test plan | E2E Agent + CI | +| 7 | PR (size, title, spec drift, CodeRabbit, human) | Git PR + human | + +### Human-in-the-Loop (Mandatory) + +- DoR blockers unresolved +- Breaking API changes +- Security-sensitive changes (auth, PII, logging) +- PR merge approval + +--- + +## 8. Jira Label and Comment State Machine + +### 8.1 Label Flow + +``` +discovery-complete → dev-ready → dev-in-progress → dev-pr-open → dev-merged → sec-input-ready +``` + +| Label | Meaning | +|-------|---------| +| `discovery-complete` | Discovery finished; awaiting Development intake | +| `dev-ready` | DoR gate passed; `spec.md` generated | +| `dev-in-progress` | Plan posted; implementation underway | +| `dev-pr-open` | Draft PR created | +| `dev-merged` | PR merged to `next` | +| `sec-input-ready` | Post-merge artifacts posted for Security phase | + +### 8.2 Comment Payloads (Durable State) + +Inter-stage state lives in **Jira comments** (same pattern as bug pipeline `scrubbed → triaged → fixed`). + +#### Intake Comment (on `dev-ready`) + +```json +{ + "harness": "development-phase", + "stage": "intake", + "ticketId": "CAI-XXXX", + "dorGate": "pass", + "blockers": [], + "specMdPath": "/tmp/claude-widgets/CAI-XXXX/spec.md", + "worktreePath": "/tmp/claude-widgets/CAI-XXXX", + "scopePackages": ["@webex/cc-task"], + "taskType": "C", + "timestamp": "2026-06-10T00:00:00Z" +} +``` + +#### Plan Comment (on `dev-in-progress`) + +```json +{ + "harness": "development-phase", + "stage": "plan", + "ticketId": "CAI-XXXX", + "planSummary": "One-line summary", + "filesToTouch": ["packages/contact-center/task/src/..."], + "testStrategy": "Unit: helper tests; E2E: SET_3 suite", + "risks": [], + "humanApprovalRequired": false, + "timestamp": "2026-06-10T00:00:00Z" +} +``` + +#### Implementation Comment + +```json +{ + "harness": "development-phase", + "stage": "implement", + "ticketId": "CAI-XXXX", + "status": "success|failed", + "testsAdded": ["path/to/test.ts"], + "testsPassing": true, + "aiDocsUpdated": false, + "timestamp": "2026-06-10T00:00:00Z" +} +``` + +#### Review Comment + +```json +{ + "harness": "development-phase", + "stage": "review", + "ticketId": "CAI-XXXX", + "blockers": [], + "suggestions": [], + "specDriftFlags": [], + "approved": true, + "timestamp": "2026-06-10T00:00:00Z" +} +``` + +#### PR Comment (on `dev-pr-open`) + +```json +{ + "harness": "development-phase", + "stage": "pr", + "ticketId": "CAI-XXXX", + "prUrl": "https://github.com/webex/widgets/pull/NNN", + "prNumber": 123, + "draft": true, + "timestamp": "2026-06-10T00:00:00Z" +} +``` + +#### Post-Merge Comment (on `dev-merged` / `sec-input-ready`) + +```json +{ + "harness": "development-phase", + "stage": "post-merge", + "ticketId": "CAI-XXXX", + "artifacts": { + "usageSpec": "link or path", + "microservicesDelta": "link or path", + "troubleshootingGuide": "link or path" + }, + "securityWorkflowTriggered": true, + "timestamp": "2026-06-10T00:00:00Z" +} +``` + +--- + +## 9. TPS Mitigations + +| Challenge | Mitigation | +|-----------|------------| +| Context poisoning | Parent summarizes MCP; subagents get JSON only | +| Agent handoff | Standard JSON schemas above; Jira comments | +| Agent persona | Fixed `.claude/agents/` definitions | +| Command vs Skills | Commands orchestrate; skills in agent prompts | +| MCP tool flooding | Phase-based router; max 3 servers/turn | +| Exit conditions | Per-agent exit in Section 4 | +| Model selection | Planner/reviewer = reasoning; implementer = coding | +| Rate limiting | Batch Jira/gh; backoff on 429 | +| Tokenomics | Plan once; reference file paths not full ai-docs | + +--- + +## 10. Dual Runtime Bindings + +### Appendix A — Claude Code + +| Command | Agents | Doc | +|---------|--------|-----| +| `/dev-start` | Orchestrator + Planner | [.claude/commands/dev-start.md](../../.claude/commands/dev-start.md) | +| `/dev-implement` | Dev Implementer | [.claude/commands/dev-implement.md](../../.claude/commands/dev-implement.md) | +| `/dev-verify` | Orchestrator | [.claude/commands/dev-verify.md](../../.claude/commands/dev-verify.md) | +| `/dev-pr` | Git PR | [.claude/commands/dev-pr.md](../../.claude/commands/dev-pr.md) | +| `/dev-review` | Cross-Verifier | [.claude/commands/dev-review.md](../../.claude/commands/dev-review.md) | +| `/dev-post-merge` | Post-Merge | [.claude/commands/dev-post-merge.md](../../.claude/commands/dev-post-merge.md) | + +Worktree: `/tmp/claude-widgets/{TICKET_ID}` + +### Appendix B — Cursor + +| Role | Configuration | +|------|---------------| +| Orchestrator | Main agent with MCP: Jira, GitHub, Confluence, Playwright | +| Subagents | Task tool: `fixer`, `qa-test-coverage`, `generalPurpose` (review), `git-pr` | +| Rules | Optional `.cursor/rules/development-phase.mdc` → this doc | +| MCP per phase | See Section 3.2 router table | + +Parent prefetches Jira; passes JSON to subagents. Fallback: parent runs `git add` if subagent cannot stage. + +### Appendix C — Widgets Repo Reference + +| Concern | Mapping | +|---------|---------| +| Task routing | AGENTS.md types A/B/C/F from ticket `taskType` in intake JSON | +| Package ai-docs | Mandatory per scope table in AGENTS.md | +| Build/test | `yarn workspace @webex/{pkg} test:unit`, `yarn build:dev`, `yarn test:e2e` | +| Architecture | Widget → Hook → Component → Store → SDK | +| Bug pipeline | Parallel to `/fix` but starts from DoR `spec.md`, not triager output | + +--- + +## 11. Out of Scope (Deferred) + +- Corona/Lambda Security AI implementation (interface documented in post-merge only) +- ContentStack MCP / Beta publish pipeline +- Tech Zone API / GTM automation +- MCP server implementations +- Threat Dragon / HAR export automation + +--- + +_Last updated: 2026-06-10_ diff --git a/ai-docs/harness/guardrails-pr-tdd.md b/ai-docs/harness/guardrails-pr-tdd.md new file mode 100644 index 000000000..62e88c38e --- /dev/null +++ b/ai-docs/harness/guardrails-pr-tdd.md @@ -0,0 +1,146 @@ +# Development Phase Guardrails — PR Size and TDD + +Proposed automated checks for the Development phase harness. **Phase 1:** document and enforce via agent checklist. **Phase 2:** wire into CI/CodeRabbit (optional implementation). + +--- + +## 1. PR Size Guardrail + +### Policy + +| Metric | Soft limit (warning) | Hard limit (block) | +|--------|----------------------|---------------------| +| Lines changed (add + delete) | 300 | 400 | +| Files changed | 12 | 15 | +| Packages touched | 2 | 3 | + +**Exceptions:** mechanical refactors, dependency bumps, generated files — require human approval comment on PR. + +### Agent Checklist (Phase 1 — Now) + +Before `/dev-pr`, orchestrator runs: + +```bash +cd {WORKTREE_PATH} +git diff --cached --stat +git diff --cached --numstat | awk '{added+=$1; deleted+=$2} END {print "lines:", added+deleted}' +git diff --cached --name-only | wc -l +``` + +If hard limit exceeded → split ticket or get human waiver in Jira before PR. + +### Proposed CI Job (Phase 2) + +Add to `.github/workflows/pull-request.yml` under `validated` label gate: + +```yaml +pr_size_check: + name: PR size guardrail + runs-on: ubuntu-latest + if: contains(github.event.pull_request.labels.*.name, 'validated') + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Check PR size + run: | + FILES=$(git diff --name-only origin/next...HEAD | wc -l) + LINES=$(git diff --numstat origin/next...HEAD | awk '{s+=$1+$2} END {print s+0}') + if [ "$FILES" -gt 15 ] || [ "$LINES" -gt 400 ]; then + echo "::error::PR exceeds size limits (files=$FILES, lines=$LINES). Split or request waiver." + exit 1 + fi +``` + +### Proposed CodeRabbit Rule (Phase 2) + +Add to `.coderabbit.yaml` under `reviews`: + +```yaml +path_instructions: + - path: "**/*" + instructions: | + Flag PRs with more than 400 total line changes or 15 files changed. + Recommend splitting unless the PR is a dependency bump or mechanical refactor. +``` + +--- + +## 2. TDD-in-Diff Guardrail + +### Policy + +Every Development phase PR that changes production code (`packages/**/src/**`) MUST include at least one new or modified test file under: + +- `packages/**/tests/**`, or +- `playwright/tests/**`, or +- `playwright/suites/**` + +**Exceptions:** docs-only, pure config, or human-documented waiver in Jira. + +### Agent Checklist (Phase 1 — Now) + +Cross-Verification Agent verifies: + +```bash +cd {WORKTREE_PATH} +# Production changes +git diff --cached --name-only | grep -E 'packages/.+/src/' || true +# Test changes +git diff --cached --name-only | grep -E '(tests/|playwright/)' || true +``` + +If production changed and no test files in diff → **blocker** in review JSON. + +Implementation Agent workflow already requires failing test first ([dev-implementer.md](../../.claude/agents/dev-implementer.md)). + +### Proposed CI Job (Phase 2) + +```yaml +tdd_diff_check: + name: TDD in diff + runs-on: ubuntu-latest + if: contains(github.event.pull_request.labels.*.name, 'validated') + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - name: Require tests when src changes + run: | + SRC=$(git diff --name-only origin/next...HEAD | grep -E 'packages/.+/src/' | wc -l) + TESTS=$(git diff --name-only origin/next...HEAD | grep -E '(tests/|playwright/)' | wc -l) + if [ "$SRC" -gt 0 ] && [ "$TESTS" -eq 0 ]; then + echo "::error::Production code changed without test file changes." + exit 1 + fi +``` + +--- + +## 3. Existing Guardrails (Already Implemented) + +| Guardrail | Where | +|-----------|-------| +| PR title format | `.github/workflows/pull-request.yml` | +| Full unit + styles on commit | `.husky/pre-commit` | +| Spec drift advisory | `.claude/commands/spec-drift-changed.md` | +| CodeRabbit auto-review | `.coderabbit.yaml` | +| FedRAMP PR template | `.github/PULL_REQUEST_TEMPLATE.md` | +| TDD methodology | Agent prompts + `superpowers:test-driven-development` | + +--- + +## 4. Integration with Development Phase + +| Phase | Guardrail | +|-------|-----------| +| Phase 2 Implement | TDD — failing test first (agent) | +| Phase 4 PR | PR size + TDD-in-diff (agent checklist) | +| Phase 4 PR | Husky + CI on merge path | +| Post-merge | N/A | + +Reference: [development-phase-plan.md](./development-phase-plan.md) Section 7. + +--- + +_Last updated: 2026-06-10_ diff --git a/ai-docs/templates/README.md b/ai-docs/templates/README.md index 63eff5757..b1e2f3763 100644 --- a/ai-docs/templates/README.md +++ b/ai-docs/templates/README.md @@ -11,7 +11,8 @@ templates/ ├── new-widget/ # Widget generation (7 modules) ├── existing-widget/ # Bug fixes, features (2 modules) ├── documentation/ # Documentation generation (2 modules, reusable for all packages) -└── playwright/ # Playwright E2E templates +├── playwright/ # Playwright E2E templates +└── development-phase/ # Development phase harness (6 modules + artifact templates) ``` ## Templates @@ -58,6 +59,24 @@ templates/ - [03-framework-and-doc-updates.md](./playwright/03-framework-and-doc-updates.md) - Shared framework/docs updates - [04-validation.md](./playwright/04-validation.md) - Validation checklist +### 5. Development Phase Harness + +**Directory:** [development-phase/](./development-phase/) + +**Orchestrator:** [../harness/development-phase-plan.md](../harness/development-phase-plan.md) + +**Modules:** +- [00-master.md](./development-phase/00-master.md) - Phase orchestrator +- [01-intake.md](./development-phase/01-intake.md) - DoR gate + spec.md +- [02-implementation.md](./development-phase/02-implementation.md) - TDD loop +- [03-verification.md](./development-phase/03-verification.md) - Build, unit, E2E gates +- [04-pr-and-review.md](./development-phase/04-pr-and-review.md) - Cross-review + PR +- [05-post-merge.md](./development-phase/05-post-merge.md) - Security/Beta/GTM handoffs + +**Artifact templates:** +- [spec.md.template](./development-phase/spec.md.template) +- [microservices-delta.md.template](./development-phase/microservices-delta.md.template) + --- ## Usage @@ -72,6 +91,8 @@ templates/ **Playwright E2E Work:** Start with [playwright/00-master.md](./playwright/00-master.md) +**Development Phase (Discovery handoff):** Start with [development-phase/00-master.md](./development-phase/00-master.md) and [harness/development-phase-plan.md](../harness/development-phase-plan.md) + ## Pattern References - [TypeScript Patterns](../patterns/typescript-patterns.md) @@ -82,4 +103,4 @@ templates/ --- -_Last Updated: 2026-03-04_ +_Last Updated: 2026-06-10_ diff --git a/ai-docs/templates/development-phase/00-master.md b/ai-docs/templates/development-phase/00-master.md new file mode 100644 index 000000000..fd5d10e33 --- /dev/null +++ b/ai-docs/templates/development-phase/00-master.md @@ -0,0 +1,110 @@ +# Development Phase Harness — Master Orchestrator + +## Purpose + +Route a Jira dev ticket from Discovery handoff through merge and post-merge artifacts. Tool-agnostic workflow; see [development-phase-plan.md](../../harness/development-phase-plan.md) for architecture. + +--- + +## When to Use + +- Jira ticket labeled `discovery-complete` or assigned to Development epic +- DoR artifacts available from Discovery phase +- Workstream: WS-2, WS-3, WS-6, WS-9 + +--- + +## Prerequisites + +Complete [01-intake.md](./01-intake.md) before any code changes. + +--- + +## Workflow Overview + +| Phase | Module | Output | +|-------|--------|--------| +| 0 Intake | [01-intake.md](./01-intake.md) | `spec.md`, label `dev-ready` | +| 1 Plan | Planner agent + Jira comment | `plan.md`, label `dev-in-progress` | +| 2 Implement | [02-implementation.md](./02-implementation.md) | Staged code + UTs | +| 3 Verify | [03-verification.md](./03-verification.md) | E2E green (or waived) | +| 4 PR & Review | [04-pr-and-review.md](./04-pr-and-review.md) | Draft PR, human review | +| 5 Post-merge | [05-post-merge.md](./05-post-merge.md) | Downstream artifacts | + +--- + +## Orchestrator Steps (Parent Agent) + +### Step 1: Fetch Context + +``` +Jira: ticket + epic + linked DoR/Feature SPEC +Confluence: optional design links +``` + +### Step 2: Intake Gate + +Run [01-intake.md](./01-intake.md). Stop if blockers. + +### Step 3: Worktree + +```bash +git worktree add /tmp/claude-widgets/{TICKET_ID} -b {TICKET_ID} +cd /tmp/claude-widgets/{TICKET_ID} +yarn install && yarn build:dev +``` + +Invoke `superpowers:using-git-worktrees`. + +### Step 4: Generate spec.md + +Copy [spec.md.template](./spec.md.template) → `spec.md`; fill from DoR + ticket. + +### Step 5: Plan → Implement → Verify → PR + +Spawn subagents in order. Pass structured JSON only (no raw MCP dumps). + +| Step | Agent | Command (Claude Code) | +|------|-------|----------------------| +| Plan | planner | `/dev-start {TICKET_ID}` | +| Implement | dev-implementer | `/dev-implement {TICKET_ID}` | +| Verify | parent + E2E agent | `/dev-verify {TICKET_ID}` | +| Review | cross-verifier | `/dev-review {TICKET_ID}` | +| PR | git-pr | `/dev-pr {TICKET_ID}` | + +### Step 6: Human Merge + +Wait for human approval. On merge → `/dev-post-merge {TICKET_ID}`. + +--- + +## Task Type Routing (Widgets Repo) + +Map `taskType` in intake JSON to AGENTS.md templates: + +| taskType | Template | +|----------|----------| +| A | [new-widget/00-master.md](../new-widget/00-master.md) | +| B | [bug-fix.md](../existing-widget/bug-fix.md) | +| C | [feature-enhancement.md](../existing-widget/feature-enhancement.md) | +| F | [playwright/00-master.md](../playwright/00-master.md) | + +Load scope `ai-docs/AGENTS.md` per [AGENTS.md](../../../AGENTS.md) package table. + +--- + +## Exit Conditions + +| Outcome | Jira label | +|---------|------------| +| Blocked at intake | `discovery-complete` (comment blockers) | +| PR open | `dev-pr-open` | +| Merged | `dev-merged` | +| Artifacts posted | `sec-input-ready` on Security epic | + +--- + +## Related + +- [development-phase-plan.md](../../harness/development-phase-plan.md) +- [guardrails-pr-tdd.md](../../harness/guardrails-pr-tdd.md) diff --git a/ai-docs/templates/development-phase/01-intake.md b/ai-docs/templates/development-phase/01-intake.md new file mode 100644 index 000000000..343125274 --- /dev/null +++ b/ai-docs/templates/development-phase/01-intake.md @@ -0,0 +1,98 @@ +# Development Phase — Intake (DoR Gate) + +## Purpose + +Verify Discovery deliverables before Development starts. Produce normalized `spec.md` and intake JSON for Jira. + +--- + +## Mandatory Pre-Step + +Do NOT proceed to planning or code until this checklist passes or human waives specific items in Jira. + +--- + +## Checklist + +### 1. Feature SPEC (CAPTURE) + +- [ ] Task list present +- [ ] Business use cases documented +- [ ] Acceptance criteria testable + +### 2. DoR Deck (Discovery) + +- [ ] High-level architecture (component communication) +- [ ] Low-level design (flows, diagrams, or sequence) +- [ ] API details (OpenAPI/Swagger or SDK method list) +- [ ] Error scenarios documented +- [ ] Limitations / blockers listed +- [ ] Open questions resolved OR explicitly deferred with owner +- [ ] Test plan (unit + E2E scope) + +### 3. Jira Ticket + +- [ ] English description complete +- [ ] Spec delta: Added / Removed / Updated +- [ ] Component scope identified +- [ ] Dependencies linked (Jira links) +- [ ] Epic linked (Dev Epic) + +### 4. Raw Data Bundle + +- [ ] PF / feature description +- [ ] Design input (Figma, screenshot, or written spec) — required for UI work +- [ ] Repo links identified +- [ ] Control Hub flags / SKU docs if applicable + +### 5. Downstream Stubs + +- [ ] Security Epic linked (for post-merge delta) +- [ ] Beta Epic linked (for usage spec expectations) + +--- + +## Blockers + +If any unchecked item is **required** for this ticket type, record in `blockers[]`: + +```json +{ + "item": "API details", + "reason": "No OpenAPI spec linked", + "owner": "Discovery", + "severity": "blocker" +} +``` + +Post to Jira; do NOT apply `dev-ready`. + +--- + +## On Pass + +1. Determine `taskType`: A (new widget) | B (bug) | C (feature) | F (playwright) +2. Determine `scopePackages`: e.g. `["@webex/cc-task"]` +3. Generate `spec.md` from [spec.md.template](./spec.md.template) +4. Create worktree (see [00-master.md](./00-master.md)) +5. Apply Jira label `dev-ready` +6. Post intake JSON comment (schema in [development-phase-plan.md](../../harness/development-phase-plan.md) §8.2) + +--- + +## Intake JSON Template + +```json +{ + "harness": "development-phase", + "stage": "intake", + "ticketId": "CAI-XXXX", + "dorGate": "pass", + "blockers": [], + "specMdPath": "/tmp/claude-widgets/CAI-XXXX/spec.md", + "worktreePath": "/tmp/claude-widgets/CAI-XXXX", + "scopePackages": ["@webex/cc-task"], + "taskType": "C", + "timestamp": "ISO-8601" +} +``` diff --git a/ai-docs/templates/development-phase/02-implementation.md b/ai-docs/templates/development-phase/02-implementation.md new file mode 100644 index 000000000..7c1fbb6e4 --- /dev/null +++ b/ai-docs/templates/development-phase/02-implementation.md @@ -0,0 +1,92 @@ +# Development Phase — Implementation (TDD Loop) + +## Purpose + +Implement changes per `spec.md` and `plan.md` using test-driven development. + +--- + +## Prerequisites + +- Intake passed (`dev-ready`) +- `plan.md` posted to Jira (`dev-in-progress`) +- Scope `ai-docs/AGENTS.md` and `ARCHITECTURE.md` read +- Relevant [patterns](../../patterns/) loaded + +--- + +## Workflow + +### 1. Read Inputs + +- `spec.md` — acceptance criteria, API, test plan +- `plan.md` — files to touch, risks +- Package ai-docs for scope + +### 2. SDK Consultation + +Before any SDK usage, consult `contact-centre-sdk-apis/contact-center.json`. Access SDK only via `store.cc.methodName()`. + +### 3. TDD Cycle + +For each acceptance criterion: + +1. **Write failing test** — describe scenario and expected outcome +2. **Run tests** — `yarn workspace @webex/{pkg} test:unit` +3. **Implement minimal code** — Widget → Hook → Component → Store → SDK +4. **Re-run until green** +5. **Refactor** if needed (keep tests green) + +Invoke `superpowers:test-driven-development`. + +### 4. Architecture Compliance + +Verify [AGENTS.md](../../../AGENTS.md) Step 5.5: + +- [ ] SDK via store only +- [ ] `observer()` on widgets +- [ ] `runInAction()` for MobX mutations +- [ ] No circular imports +- [ ] ErrorBoundary + withMetrics +- [ ] No PII in logs + +### 5. Documentation + +If public API changed: + +- Update scope `ai-docs/AGENTS.md` and/or `ARCHITECTURE.md` +- Run `/spec-drift-changed` before PR + +### 6. Stage Changes + +Stage implementation + tests. Return implementation JSON to parent. + +--- + +## Implementation JSON (Subagent Output) + +```json +{ + "ticketId": "CAI-XXXX", + "status": "success|failed", + "testsAdded": ["packages/.../tests/..."], + "testsPassing": true, + "filesChanged": ["..."], + "aiDocsUpdated": false, + "error": null +} +``` + +--- + +## Loop on Failure + +If unit tests fail after implementation → fix in worktree; do not proceed to E2E. + +--- + +## Agent + +Claude Code: [.claude/agents/dev-implementer.md](../../../.claude/agents/dev-implementer.md) + +Cursor: Task `fixer` or custom prompt with this template. diff --git a/ai-docs/templates/development-phase/03-verification.md b/ai-docs/templates/development-phase/03-verification.md new file mode 100644 index 000000000..abb23eea1 --- /dev/null +++ b/ai-docs/templates/development-phase/03-verification.md @@ -0,0 +1,81 @@ +# Development Phase — Verification + +## Purpose + +Validate implementation beyond unit tests: build, lint, architecture, E2E. + +--- + +## Layer 4 — Unit Tests (Required) + +```bash +yarn workspace @webex/{pkg} test:unit +``` + +All tests in affected packages must pass. + +--- + +## Layer 5 — Build and Lint + +```bash +yarn build:dev +yarn workspace @webex/{pkg} test:styles +``` + +Pre-commit hook runs full `yarn test:unit` + `yarn test:styles` on commit. + +--- + +## Layer 6 — E2E (Per spec.md Test Plan) + +### When Required + +- User-facing behavior changes +- Cross-widget flows affected +- `spec.md` test plan lists E2E scenarios + +### Implementation + +1. E2E agent updates tests per [playwright/ai-docs/AGENTS.md](../../../playwright/ai-docs/AGENTS.md) +2. Follow [playwright/02-test-implementation.md](../playwright/02-test-implementation.md) +3. Parent runs: + +```bash +yarn test:e2e +# Or targeted: yarn playwright test playwright/tests/{file}.spec.ts +``` + +### CI + +Add PR label `run_e2e` when E2E must run in CI (see `.github/workflows/pull-request.yml`). + +### Skip/Waiver + +Document in Jira comment with human approval: + +- Env constraints (OAuth, lab unavailable) +- Pure unit-testable logic with no UI change + +--- + +## Invoke Skill + +`superpowers:verification-before-completion` before proceeding to PR. + +--- + +## Verification Checklist + +- [ ] Unit tests green +- [ ] Build succeeds +- [ ] Styles/lint pass +- [ ] E2E green OR waived with approval +- [ ] Spec drift checked if ai-docs changed +- [ ] No console errors in sample apps (manual spot-check if UI) + +--- + +## On Failure + +Return to [02-implementation.md](./02-implementation.md) with failure logs in subagent prompt. diff --git a/ai-docs/templates/development-phase/04-pr-and-review.md b/ai-docs/templates/development-phase/04-pr-and-review.md new file mode 100644 index 000000000..707ffda7d --- /dev/null +++ b/ai-docs/templates/development-phase/04-pr-and-review.md @@ -0,0 +1,89 @@ +# Development Phase — PR and Review + +## Purpose + +Cross-agent review, guardrails, draft PR creation, human approval. + +--- + +## Step 1: Cross-Verification + +Spawn Cross-Verification Agent with: + +- `git diff --cached` (or branch diff vs `next`) +- `spec.md`, `plan.md` +- Scope ai-docs and patterns + +Review JSON must include `blockers[]`. Zero blockers required unless human overrides. + +Checks: + +- [ ] Implements all acceptance criteria in `spec.md` +- [ ] Follows architecture patterns +- [ ] TDD-in-diff: test files present when `src/` changed ([guardrails-pr-tdd.md](../../harness/guardrails-pr-tdd.md)) +- [ ] No security red flags (PII logging, direct SDK import) +- [ ] ai-docs consistent with code + +Invoke `superpowers:requesting-code-review`. + +--- + +## Step 2: PR Size Check + +Run guardrail checklist from [guardrails-pr-tdd.md](../../harness/guardrails-pr-tdd.md). + +If over hard limit → split ticket or Jira waiver before PR. + +--- + +## Step 3: Optional QA Coverage + +For new features, optionally spawn `qa-test-coverage` agent — advisory only. + +--- + +## Step 4: Create Draft PR + +Git PR Agent (or `/dev-pr` in main conversation): + +- Commit format: `{type}({scope}): {description}` +- Base branch: `next` +- Template: `.github/PULL_REQUEST_TEMPLATE.md` (FedRAMP/GAI sections) +- Default: **draft** PR + +Apply Jira label `dev-pr-open`. Post PR JSON comment. + +--- + +## Step 5: Human Review (Mandatory) + +Human must: + +- Review PR diff and test evidence +- Approve merge (or request changes) + +**Mandatory human checkpoints:** + +- Breaking API changes +- Security-sensitive changes +- Guardrail waivers + +--- + +## Step 6: Merge + +On merge: + +- Jira label: `dev-merged` +- Proceed to [05-post-merge.md](./05-post-merge.md) + +Invoke `superpowers:finishing-a-development-branch`. + +--- + +## CI Labels + +| Label | Effect | +|-------|--------| +| `validated` | Triggers title check, build, lint, unit tests | +| `run_e2e` | Triggers Playwright CI jobs | diff --git a/ai-docs/templates/development-phase/05-post-merge.md b/ai-docs/templates/development-phase/05-post-merge.md new file mode 100644 index 000000000..5edbb4d08 --- /dev/null +++ b/ai-docs/templates/development-phase/05-post-merge.md @@ -0,0 +1,97 @@ +# Development Phase — Post-Merge Artifacts + +## Purpose + +Generate handoff artifacts for Security, Beta, and GTM phases after PR merge. + +--- + +## Trigger + +PR merged to `next`; Jira ticket labeled `dev-merged`. + +Run `/dev-post-merge {TICKET_ID}` or spawn Post-Merge Agent. + +--- + +## Artifacts + +### 1. Usage SPEC (Beta Docs) + +**Consumer:** Beta Documentation phase (Phase 4) + +**Source template:** [create-agent-md.md](../documentation/create-agent-md.md) + +**Content:** + +- Public API / props / callbacks added or changed +- Usage examples +- Configuration requirements + +Attach to Beta Epic or Confluence per team process. + +--- + +### 2. microservices-delta.md (Security) + +**Consumer:** Security & Compliance phase (Phase 3) + +**Source template:** [microservices-delta.md.template](./microservices-delta.md.template) + +**Inputs:** + +- PR diff +- New/changed API endpoints +- New dependencies (from `package.json` changes) +- Data flows affecting PII/auth + +Post to Security Epic; label `sec-input-ready`. + +**Security AI workflow:** Trigger org webhook/Lambda (Corona BOM pipeline) — interface TBD; document trigger URL in team runbook. + +--- + +### 3. Troubleshooting Guide (TAC TOI / GTM) + +**Consumer:** GTM Phase 5 — TAC TOI + +Update scope `ai-docs/ARCHITECTURE.md` § Troubleshooting Guide with: + +- New failure modes +- Diagnostic steps +- Known limitations from `spec.md` + +--- + +### 4. Jira Comment + +Post post-merge JSON (schema in [development-phase-plan.md](../../harness/development-phase-plan.md) §8.2): + +```json +{ + "harness": "development-phase", + "stage": "post-merge", + "ticketId": "CAI-XXXX", + "artifacts": { + "usageSpec": "...", + "microservicesDelta": "...", + "troubleshootingGuide": "..." + }, + "securityWorkflowTriggered": true, + "timestamp": "ISO-8601" +} +``` + +--- + +## Agent + +[.claude/agents/post-merge.md](../../../.claude/agents/post-merge.md) + +--- + +## Out of Scope Here + +- Publishing to ContentStack (Beta phase) +- Threat Dragon model updates (Security phase) +- Tech Zone article publish (GTM phase) diff --git a/ai-docs/templates/development-phase/microservices-delta.md.template b/ai-docs/templates/development-phase/microservices-delta.md.template new file mode 100644 index 000000000..b8da27e83 --- /dev/null +++ b/ai-docs/templates/development-phase/microservices-delta.md.template @@ -0,0 +1,106 @@ +# Microservices Delta: {TICKET_ID} + +> Post-merge artifact for Security & Compliance phase. Generated after PR merge. + +--- + +## Metadata + +| Field | Value | +|-------|-------| +| **Ticket** | {TICKET_ID} | +| **PR** | {PR_URL} | +| **Merge commit** | {SHA} | +| **Date** | {ISO_DATE} | +| **Author** | {DEVELOPER_OR_AGENT} | + +--- + +## Summary of Change + +{One paragraph: what changed at a system/security perspective} + +--- + +## Services / Components Affected + +| Component | Path | Change type | +|-----------|------|-------------| +| | packages/contact-center/... | Added \| Updated \| Removed | + +--- + +## API Surface Changes + +### New Endpoints / SDK Methods + +| Name | Type | Auth | Data sensitivity | +|------|------|------|------------------| +| | REST / SDK | | PII / None | + +### Changed Contracts + +| Name | Before | After | Breaking | +|------|--------|-------|----------| +| | | | Yes / No | + +--- + +## Data Flow + +```mermaid +flowchart LR + UI[Widget UI] --> Store[MobX Store] + Store --> SDK[Contact Center SDK] + SDK --> Backend[Backend Service] +``` + +Describe any new data collected, stored, or transmitted: + +- {Data element — classification} + +--- + +## Dependencies (Third-Party) + +| Package | Version change | License | TPS notes | +|---------|----------------|---------|-----------| +| | | | | + +--- + +## Security Considerations + +- [ ] Authentication / authorization impact +- [ ] PII handling change +- [ ] Logging change (no credentials/PII) +- [ ] New external network calls +- [ ] Error messages leak sensitive info + +**Notes:** + +{Free text for Security team} + +--- + +## Threat Model Delta + +| Threat | Mitigation | New exposure | +|--------|------------|--------------| +| | | Yes / No | + +--- + +## Testing Evidence + +- Unit tests: {paths} +- E2E: {paths or N/A} +- Manual security testing: {notes} + +--- + +## References + +- PR diff: {link} +- Usage spec: {link} +- Threat model (if updated): {link} diff --git a/ai-docs/templates/development-phase/spec.md.template b/ai-docs/templates/development-phase/spec.md.template new file mode 100644 index 000000000..0764f3c1e --- /dev/null +++ b/ai-docs/templates/development-phase/spec.md.template @@ -0,0 +1,118 @@ +# Ticket Spec: {TICKET_ID} + +> Normalized from DoR deck + Jira spec delta. Generated at intake. + +--- + +## Metadata + +| Field | Value | +|-------|-------| +| **Ticket** | {TICKET_ID} | +| **Epic** | {EPIC_KEY} | +| **Task type** | A \| B \| C \| F | +| **Scope packages** | {PACKAGE_LIST} | +| **Author (Discovery)** | {NAME} | +| **Date** | {ISO_DATE} | + +--- + +## Summary + +{One paragraph English description from Jira} + +--- + +## Business Use Cases + +1. {Use case 1} +2. {Use case 2} + +--- + +## Acceptance Criteria + +- [ ] {Criterion 1 — testable} +- [ ] {Criterion 2 — testable} + +--- + +## Spec Delta + +### Added + +- {New behavior, API, component} + +### Updated + +- {Changed behavior} + +### Removed + +- {Deprecated/removed items, or "None"} + +--- + +## Design + +### Architecture Notes + +{High-level component communication from DoR} + +### API Details + +| Method / Prop | Type | Description | +|---------------|------|-------------| +| | | | + +**SDK methods** (verify in contact-center.json): + +- `store.cc.{methodName}()` — {purpose} + +### Error Scenarios + +| Scenario | Expected behavior | +|----------|-------------------| +| | | + +### Limitations + +- {Known limitation} + +### Open Questions + +| Question | Status | Owner | +|----------|--------|-------| +| | Resolved / Deferred | | + +--- + +## Test Plan + +### Unit Tests + +| Scenario | Package | File (planned) | +|----------|---------|----------------| +| | @webex/{pkg} | tests/... | + +### E2E Tests + +| Scenario | Playwright file / SET | Required | +|----------|----------------------|----------| +| | SET_N | Yes / No | + +--- + +## Dependencies + +- **Jira:** {linked tickets} +- **Repos:** {repo paths} +- **CH flags / SKU:** {if applicable} + +--- + +## References + +- DoR deck: {link} +- Figma / design: {link} +- OpenAPI: {link}