Document Agents

Agent Thesis

CNBS document agents create, maintain, and consume the structured documentation corpus living under docs/ and docs/archive/. These agents treat markdown files as operating memory: each agent reads its assigned input documents to establish context, produces output documents that record decisions and implementation state, and hands those outputs forward so subsequent agents begin with verified knowledge rather than reconstructed assumptions. The archive under docs/archive/agent-plans/, docs/archive/secondary-agents/, docs/archive/refactoring/, and docs/archive/stop-gap/ captures the full lineage of prior agent work, making the document loop self-auditing across the PRD lifecycle from v0.1 Spark through v1.0 Growth.

Agent Roles

Agent	Inputs	Outputs	Review Gate
ARCH-001 — Architecture Agent	`docs/ARCHITECTURE.md`, `docs/architecture/PARENT_CHILD_ORGANIZATION_ARCHITECTURE.md`, `docs/LLM_CONTEXT.md`, `next.config.ts`, `tsconfig.json`	Updated `docs/ARCHITECTURE.md`; architecture decision records under `docs/archive/`; TECH-XXX tickets	Human architect review before merge to `main`
COMP-001 — Cannabis Compliance Agent	`docs/archive/secondary-agents/03_agent_CANNABIS_COMPLIANCE_AGENT.md`, `cypress/e2e/cannabis-compliance.cy.ts`, `cypress/e2e/cannabis-purchase-limits.cy.ts`, `cypress/e2e/cannabis-transfer-manifest.cy.ts`, `cypress/e2e/cannabis-waste-tracking.cy.ts`, `cypress/e2e/regulatory-reporting.cy.ts`, `__tests__/compliance/gdpr-ccpa-compliance.test.ts`	Compliance gap reports in `docs/archive/`; updated test coverage map; BR-XXX business requirement records; state certification action plans (e.g., `docs/archive/secondary-agents/16_agent_STATE_CERTIFICATION_AGENT.md`)	Compliance officer sign-off; merged only after all Cypress compliance specs pass in `.github/workflows/cannabis-pos-testing.yml`
ANALYTICS-001 — Analytics & AI Agent	`docs/api/analytics-API-REFERENCE.md`, `docs/api/analytics-README.md`, `docs/archive/secondary-agents/01_agent_ANALYTICS_AI_SECTION_AGENT.md`, `docs/archive/summaries/ANALYTICS_AI_IMPLEMENTATION_SUMMARY.md`, API routes `/api/analytics/`, `/api/ai/`	KPI-XXX metric definitions; updated `docs/api/analytics-API-REFERENCE.md`; prediction model documentation; MON-XXX monitoring specs	Tech lead review; output docs must align with passing tests in `__tests__/integration/analytics-api.test.ts` and `__tests__/performance/customer-analytics-performance.test.ts`
POS-001 — POS Setup & Station Agent	`docs/POS_SETUP/OVERVIEW.md`, `docs/POS_SETUP/DETAILED_DESIGN.md`, `docs/POS_SETUP/README.md`, `docs/POS_SETUP/REUSE_ANALYSIS.md`, `docs/analysis/POS_STATION_REUSE_ANALYSIS.md`, `docs/analysis/POS_STATION_TRACKING_SYSTEM.md`, action plans `docs/POS_SETUP/action_plans/01_database_and_api.md` through `05_customer_connect_flow.md`	Completed action plan documents (e.g., `03_IMPLEMENTATION_COMPLETE.md`, `04_settings_management_page_COMPLETED.md`); UJ-XXX user journey maps for budtender and POS station flows	Product owner acceptance; gate is passing tests in `src/components/budtender/__tests__/BudtenderHeader.test.tsx`, `CartSidebar.test.tsx`, `ProductCard.test.tsx` and Cypress spec `cypress/e2e/pos-transaction.cy.ts`
AUTH-001 — Authentication Agent	`docs/analysis/CNBS_ADMIN_SIGNUP_ANALYSIS.md`, `docs/analysis/CNBS_AUTHENTICATION_COMPLETE_ANALYSIS.md`, `docs/analysis/COMPLETE_SIGNUP_FLOWS_ANALYSIS.md`, `docs/archive/agent-plans/ADMIN_SIGNUP_ACTION_PLAN.md`, `docs/archive/agent-plans/FINAL_AUTHENTICATION_ACTION_PLAN.md`, API routes `/api/auth/`, `/api/clerk/`	Updated authentication flow diagrams in `docs/analysis/`; BR-XXX requirements for role-based access; completed implementation plans in `docs/archive/agent-plans/`	Security review; gate is passing tests in `__tests__/security/customer-data-security.test.ts`, `src/__tests__/security/cms-security.test.ts`, and workflow `.github/workflows/pre-commit.yml`
CMS-001 — CMS & Storefront Agent	`docs/analysis/STOREFRONT_AUDIT_SYSTEM_PLAN.md`, `docs/analysis/STOREFRONT_CONFIG_PANEL_ANALYSIS.md`, `docs/archive/ecommerce-agents/01_agent_cms_content_management.md`, `docs/STYLE_RULES.md`, `e2e/cms-workflows.spec.ts`	CMS configuration guides in `docs/archive/ecommerce-agents/`; API-XXX specs for `/api/ai/generate-hero`, `/api/ai/generate-promotion`, `/api/ai/extract-colors`; widget library documentation	Design review against `docs/STYLE_RULES.md`; gate is passing `src/__tests__/cms/StorefrontConfigPanel.test.tsx`, `src/__tests__/cms/WidgetLibrary.test.tsx`, `src/__tests__/integration/cms-api.test.ts`
DATA-001 — Data Migration Agent	`docs/archive/data-migration/01_product_schema_analysis.md` through `06_strain_database_documentation.md`, `docs/archive/secondary-agents/04_agent_DATA_MIGRATION_AGENT.md`, `database/local_schema.sql`, `database/cloud_migration.sql`, `database/combined-migrations.sql`, `data-migration/*.json`	DBT-XXX migration task records; validated schema documentation in `docs/archive/data-migration/`; updated `database/migrations-to-apply.sql`	DBA review; gate is a successful `supabase db reset` run and passing `src/app/api/organizations/[orgId]/products/__tests__/bulk.integration.test.ts`
PAYMENT-001 — Payment Integration Agent	`docs/archive/secondary-agents/13_agent_PAYMENT_INTEGRATION_AGENT.md`, `docs/archive/stop-gap/action-plan/06_agent_payment_processing.md`, API route `src/app/api/payment/process/__tests__/route.test.ts`, `next.config.ts` (`@square/web-sdk`, `stripe`, `square` server external packages)	API-XXX payment endpoint specs; integration runbooks in `docs/archive/secondary-agents/`; security checklist items	Finance and security sign-off; gate is passing `src/app/api/payment/process/__tests__/route.test.ts` and no open security PRs (cf. PR #105 fix pattern)
PERF-001 — Performance & Scaling Agent	`docs/archive/secondary-agents/14_agent_PERFORMANCE_SCALING_AGENT.md`, `docs/archive/stop-gap/master-system-status.md`, `docs/archive/stop-gap/progress-dashboard.md`, `__tests__/load/real-time-analytics-load.test.ts`, `src/__tests__/performance/load-testing.ts`, `.github/workflows/performance-monitoring.yml`	MON-XXX monitoring runbooks; performance baselines in `docs/archive/summaries/`; updated thresholds in `.github/workflows/performance-monitoring.yml`	Tech lead review; gate is load test pass with no regressions in `__tests__/performance/customer-analytics-performance.test.ts`
SEC-001 — Security Audit Agent	`docs/archive/secondary-agents/15_agent_SECURITY_AUDIT_AGENT.md`, `docs/archive/stop-gap/action-plan/05_agent_authentication_security.md`, `docs/SYSTEM_SAFETY.md`, `__tests__/security/customer-data-security.test.ts`, `__tests__/compliance/gdpr-ccpa-compliance.test.ts`, `.github/workflows/pre-commit.yml`	Security audit reports in `docs/archive/`; TECH-XXX remediation tickets; updated `docs/SYSTEM_SAFETY.md`	CISO or senior engineer sign-off; gate is zero critical findings and all security test files passing in `.github/workflows/test.yml`
REFACTOR-001 — Refactoring Coordinator Agent	`docs/archive/refactoring/AGENT_01_FOUNDATION_TYPES_HOOKS.md` through `AGENT_08_TESTING_VALIDATION.md`, `docs/PROVIDER_PATTERNS.md`, `scripts/detect-hook-provider-mismatches.js`	Updated refactoring milestone documents in `docs/archive/refactoring/`; TECH-XXX tickets for hook and provider changes	Tech lead review; gate is `npm run validate:hooks` exit 0 and full Jest suite green via `npm run test:ci`
COORD-001 — Master Coordinator Agent	All agent output documents; `docs/archive/agent-plans/AGENT_HANDOFF_PROMPT.md`, `docs/archive/agent-plans/START_HERE.md`, `docs/archive/agent-plans/PARALLEL_WORK_PLAN.md`, `docs/archive/secondary-agents/11_agent_MASTER_IMPLEMENTATION_COORDINATOR.md`, `docs/archive/stop-gap/00_agent_comprehensive_system_audit_master.md`	`docs/ROADMAP.md` updates; cross-agent status in `docs/archive/stop-gap/progress-dashboard.md`; handoff prompts in `docs/archive/agent-plans/`; `docs/archive/agent-plans/QUICK_ASSIGN.md` task assignments	Product owner weekly review; no direct code gate — document completeness is the gate

Document Loop

Generated documents become source material through a three-stage cycle.

Stage 1 — Production. An agent completes a task and writes its findings to a versioned markdown file in the appropriate docs/ subdirectory. Implementation agents write to docs/POS_SETUP/action_plans/, docs/archive/ecommerce-agents/, or docs/archive/refactoring/ depending on domain. Analysis agents write to docs/analysis/. The naming convention mirrors the existing pattern: NN_agent_DOMAIN_COMPLETE.md signals a closed deliverable while NN_agent_DOMAIN.md signals an open or in-progress plan.

Stage 2 — Ingestion. The COORD-001 Master Coordinator Agent reads all newly completed documents during its weekly cycle, updates docs/ROADMAP.md and docs/archive/stop-gap/progress-dashboard.md, and reissues docs/archive/agent-plans/QUICK_ASSIGN.md with reprioritized tasks. Downstream agents — for example, PERF-001 consuming the latest compliance audit from COMP-001, or REFACTOR-001 consuming AUTH-001's updated hook inventory — pull from these coordinator-maintained indexes rather than scanning the full docs/ tree directly.

Stage 3 — Retirement. When a plan document's corresponding implementation is fully merged and verified by CI (.github/workflows/test.yml, .github/workflows/cannabis-pos-testing.yml), the COORD-001 agent moves the document from its active location to docs/archive/ and records the retirement in docs/archive/stop-gap/master-system-status.md. The archived document remains discoverable for audit and onboarding purposes but is excluded from active agent input sets, preventing stale context from polluting future work.

Test output artifacts — coverage reports from npm run test:coverage, visual regression snapshots from .github/workflows/visual-regression.yml, and load test baselines from __tests__/load/real-time-analytics-load.test.ts — feed back into PERF-001 and SEC-001 as structured data inputs during their next cycle, completing the loop between living code and living documentation.

Governance

Human review triggers. Every agent output document requires at minimum one human reviewer before it can be designated as source material for a downstream agent. Review authority is domain-scoped: compliance documents (COMP-001, SEC-001) require sign-off from a compliance officer or CISO; architecture and performance documents (ARCH-001, PERF-001, REFACTOR-001) require a tech lead; product and UX documents (POS-001, CMS-001, ANALYTICS-001) require the product owner; data and payment documents (DATA-001, PAYMENT-001) require both a DBA and a finance or security stakeholder.

Approval workflow. Documents are submitted via pull request against main following the same branch conventions visible in the recent commit history (e.g., staging, taha/tickets-2.0). The PR must reference the relevant ZP ticket ID (matching the pattern fix(ZP-NNNN) seen in commits d40c3f9 through 22451dc) and the corresponding BR-XXX, TECH-XXX, or API-XXX identifier from this ID system. The .github/workflows/pre-commit.yml hook enforces that scripts/detect-hook-provider-mismatches.js passes before any document-bearing PR can be opened.

Retirement and supersession. A document is retired when its CI gate passes on main and the COORD-001 agent has logged the closure in docs/archive/stop-gap/master-system-status.md. Superseded documents are not deleted; they are moved to the appropriate docs/archive/ subdirectory with a _COMPLETE or _ARCHIVED suffix, preserving audit lineage. Any agent that cites a retired document in a new plan must explicitly note the supersession and reference the replacement document.

Cadence. COORD-001 runs a full document audit weekly. Domain agents produce outputs per sprint. Security and compliance agents (SEC-001, COMP-001) additionally produce a mandatory review artifact after every merged PR that touches src/app/api/auth/**, src/app/api/clerk/**, src/app/api/payment/**, or any file in database/. This ensures that the GDPR/CCPA compliance posture documented in __tests__/compliance/gdpr-ccpa-compliance.test.ts remains synchronized with the deployed codebase after every change.