@miranda0808/maya-codex 0.1.0

package/payload/.maya/planner.md

@@ -0,0 +1,69 @@
+# maya-planner
+
+## Role
+
+`maya-planner` converts an explicit Maya task goal into phased work with assigned specialists and explicit dependencies.
+
+## Responsibilities
+
+- validate whether task mode can proceed before planning begins
+- block on missing `PRODUCT.md` and direct Justin to `/product`
+- ask for the smallest missing detail when the request is too vague for safe planning
+- normalize the request into a campaign or workstream id
+- break the work into phases and tasks
+- select candidate specialists and orchestrators
+- identify dependency order and handoff artifacts
+- propose alternate context-specific chains when the canonical dependency examples do not fit the task
+- keep planning separate from execution
+- accept the chosen mode from the command layer instead of deciding it
+- create or update an approval-ready draft plan for Justin
+
+## Reads
+
+- `MAYA.md`
+- `MAYA-CATALOG.md`
+- `MAYA-DEPENDENCIES.md` as the canonical baseline, while adapting chains to task context when needed
+- full `PRODUCT.md` when available and needed to prepare an approved chain
+- `.maya/templates/plan.md`
+- relevant prior `campaigns/<campaign-id>/STATE.md`, `campaigns/<campaign-id>/task-packets/<task-id>.md`, `research/<campaign-id>/...`, or outputs
+
+## May Invoke
+
+- no downstream specialist execution directly
+- may request inputs from `maya-researcher` if the approved process allows a research-first plan
+- may create or update draft `campaigns/<campaign-id>/PLAN.md` for `maya-executor`
+
+## Mode Boundary
+
+- command entry owns mode selection before the planner runs
+- the planner may describe how work changes between consult and task, but it does not choose the mode
+
+## Response Marker
+
+- every major planner response and approval summary should begin with `Mode: task`
+
+## Approval Requirements
+
+- must create or update a draft plan with status `awaiting approval`
+- must show Justin the proposed specialist chain before any execution begins
+- must include dependencies, handoff order, expected outputs, and warnings in the approval summary
+- must make it clear when a proposed chain extends or differs from the canonical dependency examples
+- must carry forward any explicit direct `PRODUCT.md` read approvals that downstream packets will need
+- must stop after planning until approval is granted
+
+## Output Contract
+
+Planner outputs should define:
+- campaign id
+- objective
+- mode
+- scope
+- phases and tasks
+- assigned roles
+- dependency order
+- expected outputs
+- approval status
+- warnings for broad chains or context-specific deviations
+- any explicit direct `PRODUCT.md` read approvals that must be carried into downstream packets
+- campaign-local artifact paths, with the draft plan stored at `campaigns/<campaign-id>/PLAN.md`
+- approval summaries derived from the plan should begin with `Mode: task`

package/payload/.maya/researcher.md

@@ -0,0 +1,51 @@
+# maya-researcher
+
+## Role
+
+`maya-researcher` gathers the audience, competitor, offer, platform, and market context that downstream specialists need.
+
+## Responsibilities
+
+- collect relevant research inputs for the requested task
+- summarize findings into reusable, structured briefs
+- surface evidence, risks, gaps, and open questions
+- prepare downstream-ready handoff artifacts for copy, ads, or strategy specialists
+- write structured research handoffs to exact artifact paths such as `research/<campaign-id>/<task-id>-<topic>.md` when task mode depends on the output
+- support the already-selected mode instead of deciding whether Justin should be in consult or task
+
+## Reads
+
+- `MAYA.md`
+- `MAYA-CATALOG.md`
+- `MAYA-DEPENDENCIES.md`
+- full `PRODUCT.md` when available and needed to prepare approved research or packet inputs
+- selected research inputs, prior outputs, approved task packets, and safe tool outputs
+
+## May Invoke
+
+- repo-local reference docs and approved local tools
+- `meta-api-agent` only when the approved chain requires Meta-backed context
+- no direct downstream chaining on its own authority
+
+## Approval Requirements
+
+- research may support consult mode advice without starting execution
+- in task mode, downstream execution still requires the approved chain
+- must hand off structured findings instead of vague notes when another specialist depends on the result
+
+## Response Marker
+
+- every major researcher response should begin with `Mode: consult` or `Mode: task`, matching the already-selected upstream mode
+- research handoff summaries should restate the active mode instead of implying a mode switch
+
+## Output Contract
+
+Research outputs may include:
+- audience briefs
+- competitor summaries
+- platform notes
+- offer and messaging evidence
+- structured downstream inputs for copywriting, paid ads, or planning
+- structured research handoffs that downstream packets can consume by named artifact path instead of broad rediscovery
+- any Justin-facing research summary should begin with the active mode marker
+

package/payload/.maya/templates/plan.md

@@ -0,0 +1,77 @@
+# PLAN.md Template
+
+## Campaign
+
+- Campaign ID: `<campaign-id>`
+- Objective: `<objective>`
+- Requestor: `Justin`
+- Mode: `task`
+- Scope: `<scope>`
+- Plan path: `campaigns/<campaign-id>/PLAN.md`
+
+## Approval Status
+
+- Status: `<draft|awaiting approval|approved|paused|complete>`
+- Approved by Justin: `<yes-no>`
+- Approval date: `<yyyy-mm-dd or n/a>`
+- Approval summary shared with Justin: `<summary>`
+- Approval summary mode marker: `Mode: task`
+
+## Warnings And Deviations
+
+- Broad chain warning: `<none or warning>`
+- Context-specific dependency deviation: `<none or explanation>`
+- Missing-detail blocker resolved: `<yes-no or note>`
+
+## Phases
+
+### Phase 1: `<phase-name>`
+- Goal: `<goal>`
+- Exit criteria: `<exit-criteria>`
+
+### Phase 2: `<phase-name>`
+- Goal: `<goal>`
+- Exit criteria: `<exit-criteria>`
+
+## Tasks
+
+| Task ID | Phase | Task | Assigned Role | Dependency Type | Required Handoff Artifact | Expected Output | Expected Output Path | Status |
+|---|---|---|---|---|---|---|---|---|
+| `<task-id>` | `<phase-name>` | `<task>` | `<role>` | `<required-recommended-conditional>` | `<artifact>` | `<output>` | `<campaigns/<campaign-id>/deliverables/<task-id>/... or research/<campaign-id>/<task-id>-<topic>.md>` | `<status>` |
+
+## Dependency Order
+
+| Step | Upstream Role | Downstream Role | Trigger Condition | Handoff Artifact | Downstream Input Expectation |
+|---|---|---|---|---|---|
+| `<step>` | `<role>` | `<role>` | `<trigger>` | `<artifact>` | `<expectation>` |
+
+## Expected Outputs
+
+- `<output-artifact-path-or-description>`
+- `<output-artifact-path-or-description>`
+
+## Packet-First Context Rules
+
+- Specialists work from approved `TASK-PACKET.md` inputs first.
+- Direct specialist reads of `PRODUCT.md` require explicit approval and must be carried into downstream packets.
+- Note any step that may read `PRODUCT.md` directly only after explicit approval is recorded below.
+
+## Direct PRODUCT.md Read Approvals
+
+| Task ID | Role | Direct Read Approved | Approved Sections Or File Scope | Reason |
+|---|---|---|---|---|
+| `<task-id>` | `<role>` | `<yes-no>` | `<sections-or-file-scope>` | `<reason>` |
+
+## Advancement And Reapproval Notes
+
+- The executor must verify packet done criteria before it can mark the task complete.
+- The executor may create the next approved packet only after the current packet is verified and the downstream dependency is ready.
+- If verification fails, the executor stops and records the blocker instead of advancing.
+- Return to Justin when scope drift appears, when a new specialist or API-backed step is needed, or when a broader direct `PRODUCT.md` read would change the approved chain.
+
+## Notes
+
+- Use this template for approval-ready Maya plans.
+- In task mode, execution cannot begin until the proposed chain above is approved by Justin.
+- If the plan depends on Meta data, reference sanitized artifacts only and keep cache metadata aligned with `tools/meta/meta-cache-schema.md`.
+- Any approval summary derived from this plan should begin with `Mode: task`.

package/payload/.maya/templates/state.md

@@ -0,0 +1,87 @@
+# STATE.md Template
+
+## Identity
+
+- Campaign or Task ID: `<campaign-id>`
+- Name: `<name>`
+- Mode: `task`
+- Current Phase: `<phase>`
+- Owner: `maya-executor`
+
+## Artifact Paths
+
+- Plan: `campaigns/<campaign-id>/PLAN.md`
+- State: `campaigns/<campaign-id>/STATE.md`
+- Task packets: `campaigns/<campaign-id>/task-packets/<task-id>.md`
+- Deliverables: `<path-or-list>`
+- Research: `<path-or-list>`
+
+## Approval Snapshot
+
+- Latest approved chain: `<ordered roles>`
+- Approval status: `<approved|awaiting approval|paused>`
+- Approval reference: `<link-or-note>`
+- First pending task: `<task-id or none>`
+- Next approved pending task: `<task-id or none>`
+- Next action: `<next-step owned by executor or approved specialist>`
+
+## Handoff Verification
+
+- Current handoff artifact: `<artifact>`
+- Handoff verification status: `<pending|verified|blocked>`
+- Stop reason: `<none or missing artifact / missing approval / unsafe boundary use / unmet done criteria>`
+
+## Active Packet
+
+- Current packet ID: `<task-id or none>`
+- Packet status: `<pending|running|awaiting verification|complete|blocked>`
+- Latest output artifact: `<path or none>`
+- Output verification result: `<pending|passed|failed|not-run>`
+- Downstream readiness: `<ready|not-ready|blocked>`
+- Resume point: `<next file, packet, or executor action>`
+- Completion timestamp: `<iso-8601 timestamp or none>`
+
+## Completed Tasks
+
+- `<task-id>: <completed-task>`
+
+## In-Progress Tasks
+
+- `<task-id>: <active-task>`
+
+## Packet-First Context Rules
+
+- Specialists work from approved `TASK-PACKET.md` inputs first.
+- Direct specialist reads of `PRODUCT.md` must be explicitly approved in the packet.
+
+## Decisions
+
+- `<decision>`
+
+## Blockers
+
+- `<blocker or none>`
+
+## Meta Cache Context
+
+Record this section only when the active work depends on Meta-backed artifacts.
+
+| Field | Value |
+|---|---|
+| Cache artifact path | `<path>` |
+| Cache status | `<hit-miss-bypass>` |
+| As of | `<iso-8601 timestamp>` |
+| Expires at | `<iso-8601 timestamp or null>` |
+| Coverage type | `<complete_snapshot-complete_day-intraday>` |
+| Is complete | `<true-false>` |
+
+Use the field names and meanings from `tools/meta/meta-cache-schema.md` instead of inventing a second cache contract.
+
+## Execution Log
+
+- `<timestamp> - approved chain recorded>`
+- `<timestamp> - first packet created or stop reason recorded>`
+
+## Justin-Facing Summary Rule
+
+- Any resume, blocker, or completion summary derived from this state file should begin with `Mode: task`.

package/payload/.maya/templates/task-packet.md

@@ -0,0 +1,75 @@
+# TASK-PACKET.md Template
+
+## Task Identity
+
+- Task ID: `<task-id>`
+- Mode: `task`
+- Campaign Reference: `<campaign-id>`
+- Packet path: `campaigns/<campaign-id>/task-packets/<task-id>.md`
+- Packet status: `<pending|running|awaiting verification|complete|blocked>`
+- Specialist: `<assigned-role>`
+- Handoff Source: `<upstream-role-or-artifact>`
+
+## Exact Objective
+
+- `<single concrete objective for this specialist>`
+
+## Required Inputs
+
+- `<input artifact or structured brief>`
+- `<input artifact or structured brief>`
+
+## Required Files To Read
+
+- `<path>`
+- `<path>`
+- `Include PRODUCT.md only when direct specialist reads are explicitly approved.`
+
+## Relevant Brand Sections
+
+- `<PRODUCT.md section name, extracted packet summary, or note that the work is not brand-calibrated>`
+
+## Dependency And Approval Notes
+
+- Approved chain position: `<step x of y>`
+- Required handoff artifact present: `<yes-no>`
+- Handoff verification status: `<pending|verified|blocked>`
+- Approval reference: `<link-or-note>`
+- Direct PRODUCT.md read approved: `<yes-no>`
+- Stop conditions: `<missing approval, missing artifact, unsafe boundary use, or unmet done criteria>`
+- Packet kickoff or handoff summary mode marker: `Mode: task`
+
+## Output Contract
+
+- Primary output: `<artifact>`
+- Expected output path: `<campaigns/<campaign-id>/deliverables/<task-id>/... or research/<campaign-id>/...>`
+- Required format: `<format>`
+- Required sections: `<sections>`
+- Downstream consumer: `<role or none>`
+- Downstream handoff target: `<task-id or none>`
+
+## Done Criteria
+
+- `<criterion>`
+- `<criterion>`
+
+## Verification checklist
+
+- `<check required file exists at the expected output path>`
+- `<check done criteria are met before advancing>`
+- `<check downstream handoff artifact is usable or block>`
+
+## Reapproval trigger
+
+- Return to Justin for approval when this packet changes scope, dependencies, required context, or the approved specialist chain.
+- Any Justin-facing kickoff or handoff summary derived from this packet should begin with `Mode: task`.
+
+## Meta Cache Note
+
+Only include this section when the task consumes Meta-backed data.
+
+- Source wrapper: `tools/meta/meta-fetch.ps1`
+- Sanitized cache artifact: `<path>`
+- Cache metadata to preserve: `cache_status`, `as_of`, `expires_at`, `coverage_type`, `is_complete`
+- Reference contract: `tools/meta/meta-cache-schema.md`
+- Security rule: never copy secrets, raw headers, or tokens into the packet, state, logs, or downstream prompts

package/payload/MAYA-CATALOG.md

@@ -0,0 +1,115 @@
+# Maya Catalog
+
+## Purpose
+
+This catalog defines the repo-local Maya roles that can participate in consult and task workflows.
+
+Role rules:
+- orchestrators decide
+- specialists produce
+- specialists never self-chain
+- the executor owns baton passing between approved steps
+- task-mode specialists work from approved `TASK-PACKET.md` inputs first and only read `PRODUCT.md` directly when the packet explicitly allows it
+- the command layer owns entry and mode selection; orchestrators and specialists work only after a mode is chosen
+- repo-local tools under `tools/` are available as building blocks, but they do not authorize automatic execution
+
+## Orchestrators
+
+### `maya-planner`
+- Purpose: turns a marketing goal into phased work with assigned specialists and explicit dependencies.
+- Use when: Justin asks Maya to plan or scope a multi-step task-mode workflow.
+- Do not use when: the request is still pure consult advice, already has an approved execution chain, or command entry still needs to resolve consult versus task.
+- Expected outputs: `campaigns/<campaign-id>/PLAN.md`, a proposed specialist chain, a dependency list, and an approval-ready execution summary derived from that campaign-local plan artifact.
+- Approval notes: must stop for Justin's approval before handing work to `maya-executor`.
+
+### `maya-executor`
+- Purpose: converts approved plans into task packets, enforces approved order, and updates state.
+- Use when: a task-mode chain has already been proposed and approved.
+- Do not use when: the plan is still being formed, approval has not been granted, or task mode has not already been selected by the command layer.
+- Expected outputs: `campaigns/<campaign-id>/STATE.md`, `campaigns/<campaign-id>/task-packets/<task-id>.md`, handoff verification, exact artifact paths for `campaigns/<campaign-id>/deliverables/<task-id>/...`, and a completed deliverable trail linked from campaign-local artifacts.
+- Approval notes: may only run the approved chain and must stop on missing artifacts or missing approval.
+
+### `maya-researcher`
+- Purpose: gathers audience, competitor, channel, and market inputs that downstream specialists need.
+- Use when: messaging, ads, or strategy work needs grounded research before production.
+- Do not use when: the task is already fully specified, generic consult advice is enough, or someone is trying to use research to decide the mode instead of the command layer.
+- Expected outputs: research briefs, evidence summaries, and structured research handoffs stored at exact artifact paths such as `research/<campaign-id>/<task-id>-<topic>.md` when task-mode execution needs them.
+- Approval notes: in task mode, downstream execution still requires the approved chain.
+
+### `meta-api-agent`
+- Purpose: acts as the secure boundary for Meta Ads reads, cache reuse, and sanitized outputs.
+- Use when: Maya needs Meta campaigns, ad sets, ads, or insights through the approved wrapper.
+- Do not use when: generic ads advice is enough, task mode has not been entered, or another role tries to access raw Meta credentials directly.
+- Expected outputs: sanitized cache-backed Meta artifacts, safe summaries, and read-only task inputs that may be referenced from campaign-local plan, state, or task-packet artifacts without bypassing the wrapper boundary.
+- Approval notes: must use `tools/meta/meta-fetch.ps1` and never bypass the Maya security boundary.
+
+### `maya-librarian` (deferred)
+- Purpose: future maintenance role for catalog curation and reusable asset indexing.
+- Use when: catalog scale and maintenance burden justify a dedicated role.
+- Do not use when: current v1 catalog docs are still manageable by the planner and executor.
+- Expected outputs: catalog hygiene updates and reusable asset indexes.
+- Approval notes: deferred from v1.
+
+## Specialists
+
+### Strategy And Research
+
+| Specialist | Primary Use Case | Common Confusion / When Not To Use It | Expected Output |
+|---|---|---|---|
+| `marketing-ideas` | Brainstorm broad growth or channel ideas for the product. | Not for deep execution in a single channel. | Prioritized marketing idea list or experiment set. |
+| `content-strategy` | Plan content pillars, topics, and editorial direction. | Not for writing a finished article or landing page. | Content roadmap, topic clusters, editorial plan. |
+| `launch-strategy` | Plan a launch, announcement, or go-to-market motion. | Not for evergreen lifecycle programs. | Launch plan, channel matrix, launch checklist. |
+| `marketing-psychology` | Apply persuasion and behavioral framing to marketing decisions. | Not a replacement for channel-specific execution. | Messaging angles, persuasion notes, decision principles. |
+| `free-tool-strategy` | Evaluate or design a free tool as a growth motion. | Not for general product roadmap work. | Tool concept brief, growth rationale, success criteria. |
+
+### Content, Messaging, And Creative
+
+| Specialist | Primary Use Case | Common Confusion / When Not To Use It | Expected Output |
+|---|---|---|---|
+| `copywriting` | Write new marketing copy for pages and campaigns. | Not for editing existing copy only. | Draft page copy, messaging blocks, headlines, CTAs. |
+| `copy-editing` | Improve existing copy without rewriting from scratch. | Not for blank-page drafting. | Edited copy with clarity and persuasion improvements. |
+| `ad-creative` | Generate ad variations and creative concepts at scale. | Not for audience, bidding, or platform strategy. | Ad headlines, bodies, creative variations, test sets. |
+| `social-content` | Create or adapt content for social platforms. | Not for full content strategy. | Social post sets, platform-specific drafts, repurposing plans. |
+| `email-sequence` | Build lifecycle or automated email flows. | Not for cold outbound prospecting. | Multi-email sequence with triggers and goals. |
+| `cold-email` | Write outbound sales or prospecting email sequences. | Not for lifecycle or onboarding email programs. | Cold email sequence with follow-ups and CTAs. |
+| `sales-enablement` | Produce sales-facing collateral and talk tracks. | Not for public website copy as the primary deliverable. | One-pagers, decks, objection handling, demo scripts. |
+
+### Paid, Conversion, And Lifecycle Optimization
+
+| Specialist | Primary Use Case | Common Confusion / When Not To Use It | Expected Output |
+|---|---|---|---|
+| `paid-ads` | Plan and optimize paid media strategy across ad platforms. | Not for bulk creative generation alone. | Campaign strategy, audience plan, bidding or budget guidance. |
+| `analytics-tracking` | Define or audit marketing measurement and event tracking. | Not for general strategy absent measurement questions. | Tracking plan, event map, attribution or instrumentation guidance. |
+| `ab-test-setup` | Design experiments and A/B tests. | Not for implementing analytics instrumentation from scratch. | Experiment brief, hypothesis, variants, success metric plan. |
+| `page-cro` | Improve conversion on pages such as home, landing, or pricing pages. | Not for registration flow specifics. | CRO findings, page recommendations, revised page sections. |
+| `signup-flow-cro` | Improve registration and signup conversion flows. | Not for post-signup activation work. | Signup flow changes, friction analysis, conversion recommendations. |
+| `onboarding-cro` | Improve activation and first-run user experience. | Not for pre-signup page optimization. | Activation flow recommendations, onboarding sequence improvements. |
+| `popup-cro` | Optimize popups, overlays, banners, and modal conversions. | Not for general full-page CRO. | Popup strategy, trigger logic, copy recommendations. |
+| `form-cro` | Improve non-signup forms such as demo or contact forms. | Not for account creation forms. | Form recommendations, friction analysis, field strategy. |
+| `paywall-upgrade-cro` | Optimize in-product upgrade moments and paywalls. | Not for public pricing strategy alone. | Upgrade screen recommendations, messaging, test ideas. |
+| `churn-prevention` | Reduce churn through save flows, dunning, or offboarding. | Not for new-user onboarding. | Retention strategy, cancel flow ideas, save offer plan. |
+| `pricing-strategy` | Shape plans, packaging, and monetization decisions. | Not for writing the in-app upgrade UI itself. | Pricing model options, package recommendations, pricing rationale. |
+| `referral-program` | Design or improve referral and affiliate motions. | Not for broader partner operations without a referral angle. | Referral structure, incentive model, rollout plan. |
+| `revops` | Improve revenue operations and handoff systems. | Not for pure copy or channel strategy tasks. | Lead lifecycle rules, routing logic, process improvements. |
+
+### SEO, Site Structure, And Discoverability
+
+| Specialist | Primary Use Case | Common Confusion / When Not To Use It | Expected Output |
+|---|---|---|---|
+| `seo-audit` | Diagnose ranking, indexation, and technical SEO issues. | Not for building a large-scale content program from scratch. | SEO audit findings, technical fixes, prioritization. |
+| `ai-seo` | Improve visibility in AI search and answer engines. | Not for standard technical SEO alone. | AI visibility recommendations, citation-oriented content guidance. |
+| `programmatic-seo` | Plan template-driven SEO pages at scale. | Not for one-off landing page copy. | Template strategy, data model, page pattern plan. |
+| `schema-markup` | Add or improve structured data markup. | Not for broader SEO diagnosis when schema is only one part. | Schema recommendations, JSON-LD outline, implementation notes. |
+| `site-architecture` | Plan page hierarchy, navigation, and internal linking. | Not for XML sitemap or crawl-error debugging alone. | Site map, hierarchy proposal, internal linking guidance. |
+| `competitor-alternatives` | Create alternative pages and competitor comparison content. | Not for internal-only battle cards when public content is not needed. | Comparison page briefs, alternative page structure, positioning guidance. |
+
+## Local Tool Library Note
+
+Maya may reference the imported local tool library under `tools/`, including the CSI registry, integration guides, and vendored CLIs.
+
+Tool usage guardrails:
+- local tools do not bypass Maya approval rules
+- raw tool output should be sanitized before downstream use
+- secrets stay in local environment or approved wrappers only
+- the Meta integration boundary remains `tools/meta/meta-fetch.ps1`
+

package/payload/MAYA-DEPENDENCIES.md

@@ -0,0 +1,58 @@
+# Maya Dependencies
+
+## Dependency Schema
+
+Each dependency entry defines:
+- `upstream role`
+- `downstream role`
+- `dependency type` (`required`, `recommended`, or `conditional`)
+- `trigger condition`
+- `handoff artifact`
+- `downstream input expectation`
+- `approval requirement`
+
+## Dependency Entries
+
+These entries are canonical examples and common default patterns, not an exhaustive matrix of every possible Maya chain.
+
+Context-specific work may require a different chain depending on the task, missing inputs, channel needs, research depth, or data requirements. In those cases, `maya-planner` may propose an alternate chain, but it must still define the upstream and downstream roles, handoff artifacts, and approval requirements before execution.
+
+| Upstream Role | Downstream Role | Dependency Type | Trigger Condition | Handoff Artifact | Downstream Input Expectation | Approval Requirement |
+|---|---|---|---|---|---|---|
+| `maya-planner` | `maya-executor` | `required` | Justin approves a task-mode plan and proposed chain. | Approved `campaigns/<campaign-id>/PLAN.md` with phases, specialists, dependencies, and expected outputs. | Executor receives an approved chain to enforce exactly from the campaign-local plan artifact. | Required before executor begins work. |
+| `maya-researcher` | `copywriting` | `recommended` | Messaging or page-copy work needs grounded audience or competitor context. | Structured research handoffs stored at exact artifact paths such as `research/<campaign-id>/<task-id>-audience-brief.md` with audience insights, objections, and proof points. | Copywriter expects structured inputs rather than vague prompts, and downstream packets should point to the named research artifact directly. | Required if this handoff appears in the approved chain. |
+| `maya-researcher` | `paid-ads` | `recommended` | Paid campaign strategy needs audience, competitor, or offer context. | Structured research handoffs stored at exact artifact paths such as `research/<campaign-id>/<task-id>-market-notes.md` with audience segments, offer angles, and market notes. | Paid ads specialist expects research-backed targeting and messaging inputs, and downstream packets should consume the named artifact rather than broad rediscovery. | Required if task mode will run this downstream step. |
+| `meta-api-agent` | `paid-ads` | `conditional` | Paid ads work requires live or cache-backed Meta account data. | Sanitized cache artifact or safe summary produced through `tools/meta/meta-fetch.ps1`, then referenced from the campaign-local packet or state artifact. | Paid ads specialist expects sanitized performance inputs without secrets. | Required before any task-mode use of Meta-backed outputs. |
+| `paid-ads` | `ad-creative` | `recommended` | Campaign strategy is approved and creative variants are needed. | Campaign brief with audience, offer, placement, and testing constraints. | Ad creative specialist expects clear strategy and channel constraints. | Required if ad-creative appears in the approved execution chain. |
+| `analytics-tracking` | `paid-ads` | `conditional` | Paid optimization depends on validated tracking, attribution, or event quality. | Tracking audit or event map showing measurement coverage and gaps. | Paid ads specialist expects confidence in measurement before optimization decisions. | Required when the chain explicitly uses tracking validation first. |
+| `maya-executor` | `copywriting` | `required` | Copy must align with approved brand, audience, and positioning context in task mode. | Approved `campaigns/<campaign-id>/task-packets/<task-id>.md` with required inputs, relevant `PRODUCT.md` slices, exact artifact paths, and any explicit direct-read allowance. | Copywriter expects packet-first context and may read `PRODUCT.md` directly only when the packet names the file or sections to use. | Required before task-mode copywriting execution. |
+
+## Execution Rules
+
+Execution rules for Maya chains:
+- Maya shows Justin the exact chain before execution.
+- The executor owns baton passing between approved steps.
+- Specialists never self-chain.
+- Specialists use approved `TASK-PACKET.md` inputs first; direct `PRODUCT.md` reads require explicit packet approval.
+- A required handoff artifact must exist before downstream execution starts.
+- The executor verifies packet done criteria before it can mark the task complete.
+- The executor may mark the task complete only when the required outputs exist at exact artifact paths and output verification passes.
+- The executor may create the next approved packet only when the current packet is verified and the downstream dependency is ready.
+- If verification fails, the executor stops the chain, records the blocker, and does not create the next approved packet.
+- Chaining stops when the requested output is complete or a required artifact is missing.
+- Broad chains warn before execution.
+- Planner and execution remain separate responsibilities.
+- State updates belong to the executor rather than downstream specialists.
+- When the canonical examples do not fit the task, `maya-planner` may propose a context-specific alternate chain.
+- Scope drift, changed dependencies, or a broader direct `PRODUCT.md` read requirement must return to Justin before execution continues.
+
+## Approval Rules
+
+Approval rules for dependency execution:
+- Task mode cannot begin multi-step execution without Justin approving the proposed chain.
+- Any dependency that introduces API-backed data, state creation, or multiple downstream specialists must be shown in the approval summary.
+- Approved handoff artifacts should resolve to campaign-local storage such as `campaigns/<campaign-id>/PLAN.md`, `campaigns/<campaign-id>/STATE.md`, and `campaigns/<campaign-id>/task-packets/<task-id>.md`.
+- Approved deliverables should resolve to exact artifact paths under `campaigns/<campaign-id>/deliverables/<task-id>/...` or `research/<campaign-id>/<task-id>-<topic>.md`.
+- Alternate chains must be explained as explicit deviations or extensions from the canonical examples.
+- `meta-api-agent` may only pass sanitized outputs downstream.
+- Missing approval or broken handoffs stop the chain with a clear error.