@miranda0808/maya-codex 0.1.0 → 0.1.2

package/README.md

@@ -14,13 +14,23 @@ npx @miranda0808/maya-codex init --target ../some-project
 ## What It Installs
 
 - portable `AGENTS.md`
-- `commands/`
+- `.env.example`
+- `.gitignore` entries for `.env` and `.env.local`
+- `commands/` compatibility docs
 - `.maya/`
 - `templates/`
 - `campaigns/README.md`
 - `research/README.md`
 - `tools/`
-- `.agent/skills/`
+- `.agents/skills/` including `/maya-consult`, `/maya-task`, and `/product`
+
+## Secrets
+
+After install, copy `.env.example` to `.env` or `.env.local` in the target repo.
+
+- `.env.local` overrides `.env` when both exist.
+- Maya keeps `.env` and `.env.local` out of git by adding them to `.gitignore`.
+- The Meta boundary auto-loads `META_ACCESS_TOKEN` and `META_AD_ACCOUNT_ID` from those files for each invocation.
 
 ## Options
 
@@ -28,3 +38,12 @@ npx @miranda0808/maya-codex init --target ../some-project
 - `--force` overwrites files Maya previously installed.
 - `--target <path>` installs into a different existing directory.
 
+
+
+## Codex Entry Skills
+
+After install, Codex App should surface these repo-local Maya entrypoints from `.agents/skills/`:
+
+- `/maya-consult`
+- `/maya-task`
+- `/product`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miranda0808/maya-codex",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "bin": {
     "maya-codex": "bin/maya-codex.js"
   },
@@ -17,3 +17,4 @@
     "node": ">=18.18 <23"
   }
 }
+

package/payload/.agents/skills/maya-consult/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: maya-consult
+description: Enter Maya consult mode for advisory, lower-cost marketing help in this repo.
+metadata:
+  version: 1.0.0
+---
+
+# Maya Consult
+
+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/.agents/skills/maya-consult/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "/maya-consult"
+  short_description: "Enter Maya consult mode"
+  default_prompt: "Load Maya consult mode for this repo, respond as Maya in consult mode, and keep the interaction advisory until Justin explicitly escalates."

package/payload/.agents/skills/maya-task/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: maya-task
+description: Enter Maya task mode for approval-gated, multi-step marketing execution in this repo.
+metadata:
+  version: 1.0.0
+---
+
+# Maya Task
+
+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/.agents/skills/maya-task/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "/maya-task"
+  short_description: "Enter Maya task mode"
+  default_prompt: "Load Maya task mode for this repo, propose the specialist chain for approval, and stay approval-gated before any execution begins."

package/payload/.agents/skills/product/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: product
+description: Create or update `PRODUCT.md` through a guided interview for this repo.
+metadata:
+  version: 1.0.0
+---
+
+# Product
+
+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 skill 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/.agents/skills/product/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "/product"
+  short_description: "Create or update PRODUCT.md"
+  default_prompt: "Create or update PRODUCT.md for this repo through a guided interview, asking one question at a time and staying outside Maya consult and task mode."

package/payload/.env.example

@@ -0,0 +1,9 @@
+# Copy this file to `.env` or `.env.local` in the Maya workspace.
+# `.env.local` overrides `.env` when both exist.
+# Local environment only. Do not commit real secrets.
+META_ACCESS_TOKEN=
+META_AD_ACCOUNT_ID=
+
+# Add other imported tool credentials only when you start using them.
+# RESEND_API_KEY=
+# GA4_ACCESS_TOKEN=

package/payload/.maya/modes/consult.md

@@ -5,7 +5,7 @@
 Consult mode is Maya's advisory path for Justin.
 
 Expected entrypoint:
-- `/maya:consult`
+- `/maya-consult`
 
 ## Mode Ownership
 
@@ -57,7 +57,8 @@ Escalation from consult mode to task mode must be explicit.
 
 Before switching, Maya should:
 - say that the work is moving from advisory mode to execution mode
-- point Justin to `/maya:task` as the execution entrypoint
+- point Justin to `/maya-task` as the execution entrypoint
 - explain that task mode requires `PRODUCT.md`, a proposed chain, and approval before execution
 
 Consult mode may suggest a task-mode chain, but it must not run that chain on its own authority.
+

package/payload/.maya/modes/task.md

@@ -5,7 +5,7 @@
 Task mode is Maya's approval-gated execution path for Justin.
 
 Expected entrypoint:
-- `/maya:task`
+- `/maya-task`
 
 ## Mode Ownership
 
@@ -95,3 +95,4 @@ Before each downstream step:
 Missing approval, missing artifacts, or unsafe boundary usage stop the chain with a clear error.
 
 New or changed downstream steps require a return to Justin for approval before task mode continues.
+

package/payload/MAYA.md

@@ -15,8 +15,8 @@ Maya:
 
 Canonical Maya entrypoints:
 
-- `/maya:consult`
-- `/maya:task`
+- `/maya-consult`
+- `/maya-task`
 
 Related repo command:
 
@@ -24,16 +24,16 @@ Related repo command:
 
 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
+- repo-local skills in `.agents/skills/` are Maya's Codex entrypoints and own explicit mode entry
+- `.agents/skills/maya-consult/` implements `/maya-consult`
+- `.agents/skills/maya-task/` implements `/maya-task`
+- `commands/` remains compatibility and documentation, while `.maya/modes/consult.md` and `.maya/modes/task.md` define detailed behavior after 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
+- `/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
 
@@ -149,3 +149,9 @@ Role rule:
 - specialists produce
 - specialists use approved `TASK-PACKET.md` inputs first and never self-chain
 - the executor owns baton passing between approved steps
+
+
+
+
+
+

package/payload/commands/maya-consult.md

@@ -3,6 +3,8 @@ description: Enter Maya consult mode
 disable-model-invocation: true
 ---
 
+Compatibility note: the Codex-visible entrypoint is `/maya-consult`; keep this command file only as a compatibility or documentation shim.
+
 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
@@ -17,7 +19,7 @@ Every major Maya response in this workflow should begin with `Mode: consult`.
 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.
+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
 
@@ -26,3 +28,4 @@ Every major Maya response in this workflow should begin with `Mode: consult`.
 - 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

@@ -3,6 +3,8 @@ description: Enter Maya task mode
 disable-model-invocation: true
 ---
 
+Compatibility note: the Codex-visible entrypoint is `/maya-task`; keep this command file only as a compatibility or documentation shim.
+
 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
@@ -36,3 +38,4 @@ Every major Maya response in this workflow should begin with `Mode: task`.
 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/tools/meta/README.md

@@ -1,55 +1,58 @@
-# Meta Tool Maintenance
-
-## Source
-
-- Vendored from the upstream `marketingskills` repository: [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills)
-- Local CLI file: `tools/clis/meta-ads.js`
-- Approved Maya boundary: `tools/meta/meta-fetch.ps1`
-- Current local API base in the vendored file: `https://graph.facebook.com/v18.0`
-
-## Usage Boundary
-
-- Agents should prefer `tools/meta/meta-fetch.ps1` for Meta reads.
-- `meta-fetch.ps1` is the Maya-owned boundary for validation, read-only allowlisting, output sanitization, and cache writes.
-- Keep secrets in environment variables only.
-- Do not place raw tokens, headers, or unsafe debug output in prompts, logs, state files, or cache files.
-
-## Maintenance Policy
-
-- Treat `tools/clis/meta-ads.js` as vendored upstream code.
-- Do not hand-maintain feature changes in the vendored file unless there is an urgent local fix.
-- When the tool stops working, Meta deprecates an API version, or we need a newer endpoint or field, check the exact upstream tool first.
-- Prefer replacing the local vendored file from upstream over accumulating local drift.
-
-## Update Triggers
-
-Review the upstream `meta-ads.js` when any of the following happens:
-
-- Meta returns version deprecation or unsupported endpoint errors.
-- Expected fields disappear or response shapes change.
-- We need a newer Graph API version than the one pinned in the vendored file.
-- The upstream `marketingskills` repo updates the same tool.
-
-## Safe Update Workflow
-
-1. Compare the local `tools/clis/meta-ads.js` with the upstream `meta-ads.js` in `coreyhaines31/marketingskills`.
-2. Prefer a clean vendor refresh instead of manually mixing old and new logic.
-3. Re-run dry-run and read-only verification commands after updating.
-4. Keep any future Maya-specific safety behavior in wrappers under `tools/meta/`, not inside the vendored CLI unless strictly necessary.
-
-## Verification After A Bump
-
-Run at minimum:
-
-```powershell
-node --check 'tools/clis/meta-ads.js'
-powershell -ExecutionPolicy Bypass -File 'tools/meta/meta-fetch.ps1' -Resource campaigns -Action list -DryRun
-powershell -ExecutionPolicy Bypass -File 'tools/meta/meta-fetch.ps1' -Resource campaigns -Action insights -Id 123 -DatePreset last_30d -DryRun
-```
-
-Confirm:
-
-- syntax still passes
-- dry-run masks authorization data
-- command structure still matches expected usage
-- no local secrets are written to files, prompts, logs, or outputs
+# Meta Tool Maintenance
+
+## Source
+
+- Vendored from the upstream `marketingskills` repository: [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills)
+- Local CLI file: `tools/clis/meta-ads.js`
+- Approved Maya boundary: `tools/meta/meta-fetch.ps1`
+- Current local API base in the vendored file: `https://graph.facebook.com/v18.0`
+
+## Usage Boundary
+
+- Agents should prefer `tools/meta/meta-fetch.ps1` for Meta reads.
+- `meta-fetch.ps1` is the Maya-owned boundary for validation, read-only allowlisting, output sanitization, env-file resolution, and cache writes.
+- Keep real secrets in repo-local `.env` or `.env.local`, or in already-loaded environment variables.
+- `meta-fetch.ps1` resolves `.env` first, then `.env.local`, while preserving explicitly set process env values.
+- Do not place raw tokens, headers, or unsafe debug output in prompts, logs, state files, or cache files.
+
+## Maintenance Policy
+
+- Treat `tools/clis/meta-ads.js` as vendored upstream code.
+- Do not hand-maintain feature changes in the vendored file unless there is an urgent local fix.
+- When the tool stops working, Meta deprecates an API version, or we need a newer endpoint or field, check the exact upstream tool first.
+- Prefer replacing the local vendored file from upstream over accumulating local drift.
+
+## Update Triggers
+
+Review the upstream `meta-ads.js` when any of the following happens:
+
+- Meta returns version deprecation or unsupported endpoint errors.
+- Expected fields disappear or response shapes change.
+- We need a newer Graph API version than the one pinned in the vendored file.
+- The upstream `marketingskills` repo updates the same tool.
+
+## Safe Update Workflow
+
+1. Compare the local `tools/clis/meta-ads.js` with the upstream `meta-ads.js` in `coreyhaines31/marketingskills`.
+2. Prefer a clean vendor refresh instead of manually mixing old and new logic.
+3. Re-run dry-run and read-only verification commands after updating.
+4. Keep any future Maya-specific safety behavior in wrappers under `tools/meta/`, not inside the vendored CLI unless strictly necessary.
+
+## Verification After A Bump
+
+Run at minimum:
+
+```powershell
+node --check 'tools/clis/meta-ads.js'
+powershell -ExecutionPolicy Bypass -File 'tools/meta/meta-fetch.test.ps1'
+powershell -ExecutionPolicy Bypass -File 'tools/meta/meta-fetch.ps1' -Resource campaigns -Action list -DryRun
+powershell -ExecutionPolicy Bypass -File 'tools/meta/meta-fetch.ps1' -Resource campaigns -Action insights -Id 123 -DatePreset last_30d -DryRun
+```
+
+Confirm:
+
+- syntax still passes
+- dry-run masks authorization data
+- `.env` and `.env.local` resolution works without leaking tokens
+- command structure still matches expected usage
+- no local secrets are written to files, prompts, logs, or outputs