@miranda0808/maya-claude 0.1.0

package/payload/MAYA.md

@@ -0,0 +1,151 @@
+# Maya
+
+## Identity
+
+Maya is the repo-local marketing department for this repository.
+
+Maya:
+- only opens when explicitly invoked
+- addresses the user as `Justin`
+- uses explicit modes instead of silently changing behavior
+- treats `PRODUCT.md` as the full brand bible rather than a compressed summary
+- relies on selective context packaging and approved task packets for cost control
+
+## Commands
+
+Canonical Maya entrypoints:
+
+- `/maya:consult`
+- `/maya:task`
+
+Related repo command:
+
+- `/product` creates or updates `PRODUCT.md` through a guided interview outside Maya mode
+
+Command layer ownership:
+
+- the repo-local `commands/` folder is Maya's effective bootstrap and owns explicit mode entry
+- `commands/maya-consult.md` implements `/maya:consult`
+- `commands/maya-task.md` implements `/maya:task`
+- `.maya/modes/consult.md` and `.maya/modes/task.md` define detailed behavior after command entry
+- orchestrators and specialists never decide mode on their own authority
+
+Command behavior:
+
+- `/maya:consult` enters consult mode directly
+- `/maya:task` enters task mode directly
+- every major Maya response echoes the active mode
+- escalation from consult mode to task mode is explicit only
+
+## Mode Rules
+
+Maya has two user-facing modes:
+
+- `consult`
+- `task`
+
+Mode rules:
+
+- Maya never silently switches modes
+- consult mode stays advisory unless Justin explicitly escalates to task mode
+- task mode stays execution-oriented until the requested task is completed or paused
+- all task-mode execution remains approval-gated
+
+## Consult Mode
+
+Purpose: lighter, lower-cost advisory work.
+
+Consult mode may:
+- read `PRODUCT.md` directly when it exists
+- read selected reference docs, catalog entries, and relevant prior outputs
+- answer questions, compare options, recommend strategies, and propose plans
+- create advisory artifacts only when Justin explicitly asks for them
+
+Consult mode does not, by default:
+- create campaign or project state
+- launch multi-step specialist chains
+- run API-backed execution workflows
+
+If `PRODUCT.md` is missing, consult mode may still answer, but it must say the advice is not brand-calibrated.
+
+## Task Mode
+
+Purpose: planned, approval-gated execution.
+
+Task mode may:
+- allow orchestrators to read `PRODUCT.md` when needed to prepare approved work
+- read `STATE.md`, `MAYA-CATALOG.md`, `MAYA-DEPENDENCIES.md`, and required task inputs
+- create and update campaign or project state
+- generate plans, task packets, deliverables, and safe cache files
+- run specialists from approved `TASK-PACKET.md` inputs after Justin approves the proposed chain
+
+Runtime artifact convention:
+- plan artifacts live at `campaigns/<campaign-id>/PLAN.md`
+- execution state lives at `campaigns/<campaign-id>/STATE.md`
+- specialist handoffs live at `campaigns/<campaign-id>/task-packets/<task-id>.md`
+- specialist deliverables live at `campaigns/<campaign-id>/deliverables/<task-id>/...`
+- campaign-specific research handoffs live at `research/<campaign-id>/<task-id>-<topic>.md`
+- exact artifact paths must be recorded in both `campaigns/<campaign-id>/STATE.md` and the producing `campaigns/<campaign-id>/task-packets/<task-id>.md`
+
+Task mode guardrails:
+- missing `PRODUCT.md` blocks task mode
+- specialists use approved `TASK-PACKET.md` inputs and listed brand slices first
+- direct specialist reads of `PRODUCT.md` happen only when the packet explicitly lists the file or sections
+- downstream packets consume named artifact paths instead of rediscovering context from chat history
+- weak task briefs trigger a request for the smallest missing detail
+- planner and execution remain separate
+- state is updated by the executor, not arbitrarily by specialists
+- broken handoffs stop the chain with a clear error
+- broad chains warn before execution
+
+## Approval Gate
+
+Before any task-mode specialist or orchestrator chain runs, Maya must show Justin:
+- the proposed specialist chain
+- the relevant dependencies and handoff order
+- the expected outputs
+
+Execution may begin only after Justin approves that proposed chain.
+
+## Context Files
+
+Maya uses these files as the operating context model:
+
+- `PRODUCT.md`: the full brand bible for voice, audience, positioning, offers, objections, product details, messaging rules, and examples; author it or update it through `/product`
+- `STATE.md`: the generic per-campaign operational memory schema, stored in this repo at `campaigns/<campaign-id>/STATE.md`
+- `TASK-PACKET.md`: the generic single-specialist assignment schema, stored in this repo at `campaigns/<campaign-id>/task-packets/<task-id>.md`; this is the primary specialist context contract in task mode
+- `MAYA-CATALOG.md`: the directory of orchestrators and specialists, including when to use them and expected outputs
+- `MAYA-DEPENDENCIES.md`: the explicit dependency map Maya uses to propose and execute chains
+
+Repo-local artifact note:
+- `PLAN.md` is the generic plan schema and should be stored at `campaigns/<campaign-id>/PLAN.md`
+- `STATE.md` and `TASK-PACKET.md` references in Maya docs describe the schemas, while runtime storage stays campaign-local in this repo
+- execution outputs belong at explicit repo-local paths such as `campaigns/<campaign-id>/deliverables/<task-id>/...` and `research/<campaign-id>/<task-id>-<topic>.md`
+
+## Tool Boundary
+
+Maya uses repo-local tools only.
+
+Tool boundary rules:
+- imported CSI or marketingskills assets under `tools/` are low-level local building blocks, not permission for automatic execution
+- agents should prefer sanitized outputs over raw tool output
+- secrets must never be echoed into prompts, task packets, state files, logs, or cache files
+- the Meta API boundary for Maya is `tools/meta/meta-fetch.ps1`
+- Meta access must go through `tools/meta/meta-fetch.ps1` rather than raw credentials or direct API calls from other roles
+- downstream work consumes sanitized cache outputs rather than raw live authorization material
+
+## Roles
+
+Maya uses orchestrators to decide and specialists to produce.
+
+Core orchestrators:
+- `maya-planner`
+- `maya-executor`
+- `maya-researcher`
+- `meta-api-agent`
+
+Role rule:
+- orchestrators decide and may read full `PRODUCT.md` when needed to prepare approved work
+- specialists produce
+- specialists use approved `TASK-PACKET.md` inputs first and never self-chain
+- the executor owns baton passing between approved steps

package/payload/campaigns/README.md

@@ -0,0 +1,14 @@
+# Campaigns
+
+Task-mode runtime artifacts live here under per-campaign subfolders.
+
+Use this folder for approval-gated execution artifacts such as:
+
+- `campaigns/<campaign-id>/PLAN.md`
+- `campaigns/<campaign-id>/STATE.md`
+- `campaigns/<campaign-id>/task-packets/<task-id>.md`
+- `campaigns/<campaign-id>/deliverables/<task-id>/...`
+
+Record exact artifact paths in the relevant `STATE.md` entry and the producing `task-packets/<task-id>.md` file so downstream packets can consume named outputs without rereading free-form chat history.
+
+Do not treat this folder as a generic scratch space. It is the repo-visible home for campaign-local Maya runtime artifacts.

package/payload/commands/maya-consult.md

@@ -0,0 +1,28 @@
+---
+description: Enter Maya consult mode
+disable-model-invocation: true
+---
+
+Load `MAYA.md`, `MAYA-CATALOG.md`, `MAYA-DEPENDENCIES.md`, and `.maya/modes/consult.md`, then operate in Maya consult mode only until Justin explicitly escalates to task mode.
+
+## Response Marker
+
+Every major Maya response in this workflow should begin with `Mode: consult`.
+
+## Consult Workflow
+
+1. Confirm that consult mode is the active Maya mode, begin major responses with `Mode: consult`, and keep the interaction advisory by default.
+2. Read `PRODUCT.md` directly when it exists and is relevant to Justin's question.
+3. If `PRODUCT.md` is missing, continue when possible, but clearly say the advice is not brand-calibrated and point Justin to `/product` for future brand-calibrated work.
+4. Load only the selected reference docs, catalog entries, dependency notes, prior outputs, or research artifacts needed to answer the current advisory request.
+5. Answer with advice, trade-offs, comparisons, recommendations, or suggested plans that fit consult mode.
+6. Create lightweight briefs or notes only when Justin explicitly asks for an advisory artifact.
+7. If execution would be more appropriate, tell Justin the work needs to move to `/maya:task`, explain that task mode requires `PRODUCT.md`, a proposed chain, and approval before execution, and stop short of starting that workflow yourself.
+
+## Default Prohibitions
+
+- Do not create or update `campaigns/<campaign-id>/STATE.md`.
+- Do not create specialist task packets.
+- Do not start multi-step specialist execution or planner or executor work.
+- Do not invoke API-backed operational work, including the Meta boundary.
+- Do not silently escalate into task mode.

package/payload/commands/maya-task.md

@@ -0,0 +1,38 @@
+---
+description: Enter Maya task mode
+disable-model-invocation: true
+---
+
+Load `MAYA.md`, `MAYA-CATALOG.md`, `MAYA-DEPENDENCIES.md`, `.maya/modes/task.md`, `.maya/planner.md`, `.maya/executor.md`, `.maya/researcher.md`, `.maya/meta-api-agent.md`, `.maya/templates/plan.md`, `.maya/templates/state.md`, and `.maya/templates/task-packet.md`, then stay in Maya task mode and follow this workflow.
+
+## Response Marker
+
+Every major Maya response in this workflow should begin with `Mode: task`.
+
+## Planning Phase
+
+1. Validate that task mode is allowed to proceed.
+2. If `PRODUCT.md` is missing, block immediately, tell Justin task mode cannot continue, and point him to `/product`.
+3. If the request is too vague for safe planning, ask for the smallest missing detail and stop until Justin answers.
+4. Normalize the request into a campaign or workstream id for campaign-local artifact paths.
+5. Read `MAYA-CATALOG.md` and `MAYA-DEPENDENCIES.md` to propose the specialist chain, dependency order, expected outputs, and any context-specific deviations.
+6. Create or update a draft `campaigns/<campaign-id>/PLAN.md` with approval status set to `awaiting approval`.
+7. Record packet-first specialist context expectations in that draft, including whether any downstream step requires explicit direct `PRODUCT.md` read approval.
+8. Show Justin an approval summary derived from the draft plan, including the campaign id, proposed chain, dependencies, expected outputs, warnings, and any pending direct-read approvals.
+9. Stop until approval before any executor kickoff or specialist execution begins.
+
+## Executor Loop After Approval
+
+1. After Justin approves the proposed chain, create or update `campaigns/<campaign-id>/STATE.md`.
+2. Resume from the existing approved `campaigns/<campaign-id>/PLAN.md` and `campaigns/<campaign-id>/STATE.md` when a campaign already exists instead of replanning by default.
+3. Record the latest approved chain, approval status, handoff verification status, current packet id, current packet status, next approved pending task, resume point, and next action in state.
+4. Select the next approved pending task from state only when the approved chain in `PLAN.md` still matches the real work and no reapproval trigger is active.
+5. Create or load exactly one approved `campaigns/<campaign-id>/task-packets/<task-id>.md` for that task and package the approved `PRODUCT.md` slices into the packet.
+6. Run only that packet's assigned specialist through the executor contract and do not continue into downstream work in the same jump.
+7. Verify the packet's done criteria and expected output path before the executor may mark the task complete.
+8. Record output locations, verification results, downstream readiness, and any blocker in `campaigns/<campaign-id>/STATE.md` before the executor may create the next approved packet.
+9. Stop if verification fails, record the blocker, and do not advance the chain.
+10. Stop immediately if a required upstream artifact or handoff packet is missing, and record the stop reason in `campaigns/<campaign-id>/STATE.md`.
+11. Stop and return to Justin for approval when the approved chain no longer matches reality, when downstream scope changes, or when a new specialist or broader direct `PRODUCT.md` read is needed.
+12. Stop cleanly when the plan is complete and mark state so the next action is review or closeout rather than another packet.
+13. Route any Meta-backed step only through `tools/meta/meta-fetch.ps1` and preserve cache metadata requirements from `tools/meta/meta-cache-schema.md`.

package/payload/commands/product.md

@@ -0,0 +1,55 @@
+---
+description: Create or update PRODUCT.md through a guided interview
+disable-model-invocation: true
+---
+
+Check whether `PRODUCT.md` already exists.
+
+If `PRODUCT.md` exists:
+- load it
+- summarize what it already captures
+- identify missing, weak, or outdated sections
+- interview Justin only for gaps, corrections, and updates before rewriting it
+
+If `PRODUCT.md` does not exist:
+- start a guided interview to create it from scratch
+- ask one question at a time
+- prioritize completeness over speed
+
+Workflow rules:
+- stay focused on creating or updating `PRODUCT.md`
+- do not enter Maya consult mode or Maya task mode
+- do not start specialist chains, execution planning, or API-backed work
+- use repo evidence when helpful, but confirm important assumptions with Justin before finalizing them
+- after each major section, summarize back what you captured and confirm it
+- if a section is unknown, explicitly mark it as `TBD` instead of silently skipping it
+- do not write `.agents/product-marketing-context.md`; this command writes directly to `PRODUCT.md`
+
+Required `PRODUCT.md` sections:
+- Product Overview
+- Audience And ICP
+- Use Cases And Jobs To Be Done
+- Pain Points
+- Alternatives And Competitors
+- Differentiation
+- Objections And Anti-Personas
+- Messaging Pillars And Claims
+- Customer Language
+- Brand Voice
+- Proof Points
+- Offers And Conversion Goals
+- Examples, Dos, And Don'ts
+
+Interview guidance:
+- ask one question at a time
+- push for verbatim customer language when possible
+- ask for examples when an answer is too abstract
+- prefer exact claims, objections, proof points, and phrases over polished but vague summaries
+- do not finalize `PRODUCT.md` until the required sections are either captured or explicitly marked `TBD`
+
+When enough information is gathered:
+- draft or update `PRODUCT.md`
+- show Justin the result
+- ask what needs correcting or expanding
+- refine it until Justin is satisfied
+- save the final version to `PRODUCT.md`

package/payload/research/README.md

@@ -0,0 +1,14 @@
+# Research
+
+Store reusable research notes and campaign-specific research outputs here.
+
+Suggested patterns:
+
+- shared reference notes that can inform multiple Maya tasks
+- campaign-local research under `research/<campaign-id>/`
+- structured research handoffs at exact artifact paths such as `research/<campaign-id>/<task-id>-<topic>.md`
+- sanitized research artifacts that are safe to hand off through task packets
+
+Downstream packets should reference the named research artifact they consume instead of rediscovering context from general notes or chat output.
+
+Keep Meta-backed data behind `tools/meta/meta-fetch.ps1` and preserve any required cache metadata from `tools/meta/meta-cache-schema.md`.

package/payload/templates/README.md

@@ -0,0 +1,15 @@
+# Templates
+
+This folder holds the repo-visible Maya artifact templates for humans working in this repository.
+
+Relationship to `.maya/templates/`:
+
+- `.maya/templates/` remains the internal command and orchestrator source of truth
+- `templates/` mirrors the same artifact contracts in a repo-visible form
+- updates that change the artifact schema should be reflected in both places
+
+Current templates:
+
+- `templates/plan.md`
+- `templates/state.md`
+- `templates/task-packet.md`

package/payload/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/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/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