Skip to main content

Test Spec Writing Handoff — Continue From Here

Previous agent completed: 39 new specs across 8 categories. All committed to knowledge/master and pushed. GitHub Action auto-syncing YAML → Supabase DB → Portal now live.

Your job: Write the remaining ~46 specs to reach 100% coverage.

What Was Done (Don't Repeat)​

These categories are complete:

  • ✅ Tier Acceptance (6 specs): all tiers, all products
  • ✅ Personas (8 specs): evaluators, skeptics, privacy, IT, multi-tradition
  • ✅ Theological (8 specs): 5 traditions + safety + inclusivity
  • ✅ Consistency (4 specs): pricing, features, copy accuracy
  • ✅ Cross-Property (2 specs): product integrations
  • ✅ Known Bugs (5 specs): regression tests
  • ✅ SermonWise (4 specs): workflow discovery to daily use

Started but incomplete:

  • Journeys (1 of 9 done): admin-daily-dashboard ✓ — need 8 more
  • CRUD (1 of 10 done): chatbot-config ✓ — need 9 more

System Overview (Copy This Pattern)​

Location: C:\dev\knowledge\tests\specs\<id>.yaml

Required fields:

id: kebab-case-id                    # matches filename
title: Human Readable Title
property: churchwiseai-web           # (or pewsearch, illustratetheword, etc)
category: ux_flow                    # (see schema for all 11 options)
critical_path: false                 # only true for money/data flows

steps:
  - action: "What the tester does"
    expected: "What should happen"

Optional but recommended:

  • persona, tier, touchpoint — context for the test
  • preconditions — setup needed
  • failure_modes — what can go wrong
  • linked_code_files — which files this exercises
  • linked_acceptance_spec — reference acceptance doc
  • playwright_ref — which Playwright file implements this
  • notes — context for future readers

Auto-syncing: Push to knowledge/master → GitHub Action → test_specs DB + portal rebuild

What Remains (~46 specs)​

Priority 1: User Journeys (8 specs) — HIGH VALUE​

These test complete end-to-end flows, not just features. Reference knowledge/journeys/*.md for persona/context.

In /e2e/journeys/ but need YAML specs:

  • admin-daily-dashboard ✅ (done)
  • denomination-experience — pastor from specific tradition using all features
  • pro-both — full Pro Both journey: signup → dashboard → configure voice → test → ongoing use
  • pro-suite-chat — Pro Suite Chat journey
  • starter-both — Starter Both bundle journey
  • starter-chat — Starter Chat journey
  • suite-both — Suite Both highest-tier journey
  • trial-expired — what happens when 14-day trial ends without purchase

Pattern: Journey specs are longer (12-15 steps) and test a full user lifecycle, not just one feature.

Priority 2: CRUD Operations (9 specs) — HIGH VALUE​

Admin CRUD workflows. Each spec tests Create, Read, Update, Delete for a resource.

In /e2e/ root:

  • crud-chatbot-config ✅ (done)
  • crud-admin-care — create/edit/delete care agent personality/rules
  • crud-admin-settings — church settings, billing, team members
  • crud-admin-training — upload/manage training documents for KB
  • crud-contact — manage visitor/prayer request contacts
  • crud-social-campaigns — create/edit/delete social media campaigns
  • crud-social-platforms — connect/manage social platforms (Facebook, etc)
  • crud-social-posts — create/schedule/publish social posts
  • crud-social-settings — configure social media settings

Pattern: CRUD specs are mid-length (10-12 steps) covering create → read → update → delete flows.

Priority 3: Edge Cases (4 specs) — CORRECTNESS​

Security and boundary testing.

In /e2e/edge-*.spec.ts:

  • edge-chatbot — XSS injection, prompt injection, malformed input
  • edge-cross-site — CORS, cross-origin requests, frame embedding
  • edge-input-validation — phone numbers, emails, special chars, length limits
  • edge-rate-limiting — API rate limits, chatbot throttling, abuse prevention

Pattern: Edge case specs are shorter (8-10 steps) and focus on error paths and boundary conditions.

Priority 4: Smoke Tests & Production (8 specs) — SANITY CHECKS​

Quick health checks and integration tests.

In /e2e/ root:

  • production-smoke ✅ (already exists)
  • smoke — basic sanity: sites load, no 500 errors, nav works
  • production-journeys — full journey on production URL, not localhost
  • journey-chatbot-signup — signup → chatbot ready, end-to-end
  • journey-sermon-checkout — find sermon → checkout → access
  • journey-suite-signup — sign up for Suite tier → full access
  • journey-external-products — using external integrations (Stripe, etc)

Pattern: Smoke specs are short (6-8 steps) and verify happy-path functionality.

Priority 5: API & Integration (6 specs) — DEVELOPER EXPERIENCE​

API documentation and integration points.

In /e2e/ root:

  • api — API endpoints exist, return correct schema, auth works
  • api-new-routes — new API endpoints in latest release
  • env-integration — environment variables, config, secrets handling
  • stripe-synthetic-validator — Stripe test card flows, webhook delivery
  • care — Care Agent API and functionality
  • email-link-audit — magic link emails, unsubscribe, deliverability

Pattern: API specs are mid-length (10-12 steps) testing endpoint behavior and integration.

Priority 6: SEO, Brand, Legal (5 specs) — COMPLIANCE​

Marketing, branding, and legal requirements.

In /e2e/ root:

  • p4-seo-metadata — meta tags, Open Graph, structured data
  • p5-content-accuracy — product claims match reality, no stale copy
  • p7-branding — color, typography, logo usage consistent
  • legal-pages — privacy, terms, cookies, disclosures accessible
  • onboard — onboarding flow is clear, completes successfully

Pattern: Compliance specs are mid-length (10 steps) and check content/config, not interaction.

Priority 7: Visual & Other (4 specs) — POLISH​

Visual regression and miscellaneous.

  • visual — desktop UI visual regression (colors, layout, spacing)
  • visual-mobile — mobile UI visual regression
  • admin-dashboard — full admin dashboard feature coverage
  • payment-flow — complete payment processing end-to-end

How to Write Efficiently​

  1. Read the Playwright file first (e2e/delivers/*/xxx.spec.ts)

    • It shows what the test actually checks
    • You're creating a YAML summary of those checks

  2. Find acceptance spec if it exists (knowledge/acceptance/*.md)

    • Gives you detailed expected outputs
    • Reference in linked_acceptance_spec field

  3. Use existing spec as template

    • Find one in similar category
    • Copy structure, adapt content
    • Keep field names consistent

  4. Keep steps concrete, not vague

    • ❌ BAD: "Check that chatbot works"
    • ✅ GOOD: "Ask chatbot a question. Verify response within 30 seconds, uses HEAR protocol, addresses the question asked."

  5. Write 1-2 sentence notes

    • Explain why this test matters
    • Reference related docs/files

  6. Batch by category

    • Write all journeys together (faster context switching)
    • Then all CRUD ops
    • Then edge cases

Testing Your Work​

After writing specs:

# Validate against schema
cd C:\dev\knowledge
pnpm derive --check

# Check for syntax errors
cat tests/specs/your-spec.yaml | yq eval . - > /dev/null

If validation passes, commit and push:

git add tests/specs/*.yaml
git commit -m "feat: add X specs for [category]"
git push origin master

GitHub Action will auto-sync within 2 min.

Key References​

  • Spec schema: knowledge/tests/specs/_schema.md
  • JSON Schema: knowledge/tests/specs/_schema.json
  • How to add specs: knowledge/tests/specs/README.md
  • Portal: https://docs-portal-chi.vercel.app/tests/specs
  • Playwright files: churchwiseai-web/e2e/
  • Acceptance specs: knowledge/acceptance/
  • Journeys: knowledge/journeys/

Next Agent: Start Here​

  1. ✅ Read this file (you're doing it)
  2. Pick Priority 1 (Journeys) — highest value
  3. For each journey:
    • Read the Playwright file (e2e/journeys/xxx.spec.ts)
    • Read the acceptance spec if exists (knowledge/acceptance/xxx.md)
    • Write YAML spec in knowledge/tests/specs/journey-xxx.yaml
  4. After 3-4 journey specs, commit and push
  5. Move to Priority 2 (CRUD) — same process
  6. Continue down priority list

Status Tracking​

  • Tier acceptance (6/6)
  • Personas (8/8)
  • Theological (8/8)
  • Consistency (4/4)
  • Cross-property (2/2)
  • Known bugs (5/5)
  • SermonWise (4/4)
  • Journeys (1/9) ← START HERE
  • CRUD (1/10)
  • Edge cases (0/4)
  • Smoke tests (1/8)
  • API/Integration (0/6)
  • SEO/Brand/Legal (0/5)
  • Visual & other (0/4)

Current: 64 specs | Target: 110 specs | Remaining: ~46 specs

Good luck! The pattern is established, just need volume now. 🚀