Skip to main content

Knowledge > Runbooks > Agent Ops > How to Start a New Agent Task Correctly

How to Start a New Agent Task Correctly

Follow this checklist before writing a single line of code or making any database change. Skipping steps here is how bugs reach production.

Prerequisites​

  • Task description from the founder or task queue
  • Access to C:\dev\ and all codebases

Checklist​

1. Read the Core Docs (Non-Negotiable)​

Read these in order — do not skip or skim:

  • C:\dev\CLAUDE.md — cross-project rules, codebase ownership, agent tooling, safety rules
  • C:\dev\AGENT_QUALITY_PRINCIPLES.md — 35 principles derived from 165 real bugs. Read before any code.
  • C:\dev\QA_CHECKLIST.md — 9-section checklist you will run before declaring done

If you have already read these in the current session, confirm they haven't changed (check last-modified timestamp if uncertain).

2. Check for Blocking P0 Actions​

Review C:\dev\FOUNDER_ACTIONS.md for any P0 items that block the task you are about to start. If a P0 item blocks your work (e.g., a missing API key, an unresolved data issue), surface it to the founder before proceeding.

3. Identify the Correct Codebase​

If the task involves...Use this codebase
AI products (chatbot, voice, admin dashboard, marketing)C:\dev\churchwiseai-web\
Church directory, claim flow, Premium PagesC:\dev\pewsearch\web\
Sermon illustrationsC:\dev\sermon-illustrations\
Voice agent logic (Python, LiveKit)C:\dev\churchwiseai-web\voice-agent-livekit\
Reading reference code (B2C app patterns)C:\dev\ai-sermon-assistant\ (read only — NEVER build here)

NEVER build new features in ai-sermon-assistant/ — it is legacy reference code.

Read the codebase's own CLAUDE.md before working in it.

4. Check the Feature Registry (if Building a New Feature)​

C:\dev\FEATURE_REGISTRY.md

Before building:

  • If the feature is listed under a different property → STOP, ask the founder
  • If the feature is marked unapproved → do NOT build it
  • If the feature is not listed → warn the founder, explain where you plan to build it
  • If the feature is listed and approved → proceed, add it to the registry when done

See feature-registry-maintenance.md for the full workflow.

5. Read Relevant Knowledge Docs​

Identify which canonical knowledge files are relevant to the task:

Task typeRead these
Pricing, Stripe, checkoutknowledge/data/pricing.yaml, C:\dev\PRICING.md
Features, plan limitsknowledge/data/features.yaml
Marketing copy, product claimsknowledge/data/products.yaml, knowledge/narrative/brand.md
Customer policiesknowledge/data/policies.yaml
Competitive positioningknowledge/narrative/competitive.md
Demo/sales contentknowledge/narrative/sales-playbook.md

Always verify marketing copy against product_knowledge table when editing any marketing page:

SELECT question, answer FROM product_knowledge WHERE is_active = true ORDER BY priority DESC;

6. Create a Feature Branch​

Always create your own branch from the deploy branch. Never work directly on main or master.

# For churchwiseai-web
cd /c/dev/churchwiseai-web
git checkout main && git pull
git checkout -b feat/short-description-of-task

# For pewsearch
cd /c/dev/pewsearch/web
git checkout master && git pull
git checkout -b feat/short-description-of-task

# For sermon-illustrations
cd /c/dev/sermon-illustrations
git checkout master && git pull
git checkout -b feat/short-description-of-task

See multi-agent-git.md for full git safety rules.

7. Save a Plan File for Complex Tasks​

For any task with more than ~5 steps or multiple phases, save a plan before starting:

# Save plan to the standard location
# File: C:\Users\johnm\.claude\plans\task-short-name.md

Include: task goal, steps, open questions, risks. Update the plan as you learn more.

8. Begin Work​

With all of the above complete, begin implementation. As you work:

  • Fix ALL issues found in QA — never defer
  • Update knowledge docs if you change code they reference
  • Append to DECISION_LOG.md for any significant decision
  • Use the demo church UUID 00000000-0000-4000-a000-000000000001 for any DB testing

Before Declaring Done​

Run through C:\dev\QA_CHECKLIST.md fully. See qa-checklist-runbook.md for how to do this well.

See Also​