@mytegroupinc/myte-core

Implementation package for the myte CLI.

Most users should install the public wrapper instead:

• npm install myte
• run with npx myte ...

This package exists so the public wrapper can stay small and versioned cleanly. It is not the recommended public install target.

Requirements

• Node 18+
• MYTE_API_KEY for project-scoped commands
• MYTEAI_API_KEY for myte ai
• git only when using query --with-diff
• No runtime npm dependencies. The CLI uses Node 18+ built-ins for env loading, argument parsing, HTTP, and local context serialization.

Behavior Summary

• Snapshot-style commands such as bootstrap, sync-qaqc, feedback-sync, and suggestions sync write local MyteCommandCenter data.
• feedback status|edit|assign|archive writes reviewable local YAML artifacts; feedback submit|revise|reviews|review routes them through the backend owner-review membrane.
• feedback move|undo|prd-versions|prd-diff|history calls the project-key Feedback API while leaving lifecycle rules and permissions server-side. feedback move --feedback-ids sends one batch move request.
• feedback validate|apply remains available for validation and owner-direct apply paths; live authorization, stale checks, and history stay server-side.
• query --with-diff requires project repos to be configured for diff collection and fails fast when no matching local project repo can be resolved.
• Public package documentation is intentionally minimal. Internal rollout and design notes are not part of the npm package contract.

Agent Usage Contract

Coding agents should treat MYTE_API_KEY as a project-scoped Project Assistant key:

• Load it from the workspace .env or environment. MYTE_PROJECT_API_KEY is accepted as a compatibility fallback.
• Call myte config --json first when project identity or local repo detection is uncertain.
• Hydrate mission context with bootstrap first instead of scraping the web UI. bootstrap writes mission cards and mission suggestion thread state.
• Use suggestions sync only when you need to refresh mission review-thread state without refreshing the full board.
• Use query --with-diff for project-scoped code review, planning, and implementation questions.
• Use create-prd only with reviewed markdown files. The markdown file body is the PRD document; description is only the short board/card summary.
• Use feedback status|edit|assign|archive for reviewable local artifacts, feedback submit for owner review, and feedback review for owner/delegate decisions.
• Use feedback review --request-ids for batch owner/delegate decisions; it sends one grouped backend batch, not one request per item.
• Use suggestions create for both existing-mission edits and new-mission proposals. The only valid change_type values are update and create.
• Use suggestions revise only against an existing suggestion_id; do not send change_type on revisions because the backend keeps the thread's original type.
• Use suggestions review for owner/elevated mission-review decisions: approve, request_changes, or reject.
• Use mission archive for project-key lifecycle archival. Do not send Archived through mission status; restore archived missions from the web archived-board view.
• Use feedback move only when a direct audited state move is intended and include a concrete --reason. Use --feedback-ids for batch active-state moves or authorized batch archive.
• Do not use the project-key API/CLI to unarchive Feedback. Normal feedback-sync excludes archived Feedback; unarchive from the web archived Feedback view.
• Use update-team when an agent needs to leave a project-level implementation note or verification comment.

Do not use MYTE_API_KEY against account/JWT web endpoints. The direct project-key surface is /api/project-assistant/*.

PRD document contract:

• Always put the complete PRD in the markdown file passed to myte create-prd.
• title maps to the feedback/board title.
• description maps to the short feedback/card summary and must not contain the full PRD.
• Raw markdown uploads send { title, description?, prd_markdown }.
• myte-kanban uploads send { ticket_markdown }, where the leading JSON block contains metadata and the remaining markdown is the PRD body.
• The backend stores the markdown as prd_markdown, mirrors it as PRD text for search/sync, generates a DOCX attachment from it, and marks prd_format=markdown.
• The UI renders the PRD from stored PRD text/document content, not from description.
• Renderer-friendly PRDs should use one # Title, ## sections, concise paragraphs, bullets, GitHub tables/checklists where useful, and fenced code blocks only for real code/config.
• Do not wrap the whole PRD in a ```markdown fence. Do not use raw HTML, inline style blocks, or decorative banners.
• PRD identity is explicit: myte create-prd creates a PRD asset with PRD metadata. Generic uploaded .md, .docx, .pdf, and .txt files remain normal attachments unless explicitly created as PRDs.

Feedback comment support:

• feedback-sync includes existing feedback comment turns in local context.
• Feedback-specific comment creation exists in the web backend at /api/feedbacks/<feedback_id>/comments, protected by JWT/project assignment.
• There is no project-key CLI command for myte feedback comment yet. That requires a Project Assistant feedback-comment route plus npm command before agents should rely on it.

Mission Action Map

| Action | Command / Surface | Contract | | --- | --- | --- | | Sync mission cards and review threads | myte bootstrap --json | Refreshes MyteCommandCenter/data/missions/*.yml, project structure, and MyteCommandCenter/data/mission-ops.yml. | | Sync only mission review threads | myte suggestions sync --json | Refreshes MyteCommandCenter/data/mission-ops.yml while preserving local workspace drafts. | | Suggest edit to existing mission | myte suggestions create with change_type: update and mission_id | Creates or appends to an active review thread; live mission is unchanged until approval. | | Suggest new mission | myte suggestions create with change_type: create | Requires change_set.title and change_set.description; creates a review thread only; the mission card is created only after approval. | | Revise a suggestion | myte suggestions revise with suggestion_id | Adds another revision to the same thread. Do not include change_type. | | Review a suggestion | myte suggestions review with review_action: approve|request_changes|reject | Project Owner or elevated mission-review delegate required. Approval mutates/creates the mission once; reject archives the thread only; request_changes keeps it actionable. | | Update mission status | myte mission status --mission-ids "M001" --status todo|in_progress|done | Project-key surface updates canonical mission status for active cards and refreshes local bootstrap + mission-ops by default. | | Archive mission | myte mission archive --mission-ids "M001[,M002]" --reason "..." | Project Owner or elevated delegate required. Sets Archived, removes cards from normal bootstrap/board state, writes mission activity, and refreshes local bootstrap + mission-ops by default. |

Create payloads:

items:
  - change_type: update
    mission_id: M001
    change_description: Tighten acceptance criteria
    change_set:
      acceptance_criteria:
        - The API returns a stable error code for invalid input.

items:
  - change_type: create
    change_description: Add observability mission
    change_set:
      title: Add mission observability
      description: Track mission lifecycle actions with safe audit metadata.

Revise payload:

items:
  - suggestion_id: 507f1f77bcf86cd799439302
    expected_revision: 1
    change_description: Revise after review
    change_set:
      description: Updated proposed mission description.

YAML note: quote scalar values that contain : or other YAML-significant punctuation.

Finding Mission And Suggestion IDs

Run this first:

myte bootstrap --json

Then read:

| Needed Value | Local Source | | --- | --- | | Existing mission business id | MyteCommandCenter/data/missions/*.yml -> mission_id, for example M001. | | Pending suggestion id | MyteCommandCenter/data/mission-ops.yml -> queue[].suggestion_id or threads[].suggestion_id. | | Existing suggestion latest revision | MyteCommandCenter/data/mission-ops.yml -> threads[].latest_revision or threads[].latest_server_revision.revision. | | Existing suggestion review revision | MyteCommandCenter/data/mission-ops.yml -> threads[].review_revision. | | Thread type | MyteCommandCenter/data/mission-ops.yml -> threads[].change_type, either update or create. |

Agent rule: never guess suggestion_id. If mission-ops.yml is missing or stale, run myte bootstrap --json again. Use myte suggestions sync --json only for a narrow refresh after a mutation.

Feedback Action Map

| Command | What It Does | Governance | | --- | --- | --- | | feedback-sync | Pulls non-archived feedback metadata, comments, and PRD context into MyteCommandCenter. | Read-only project-key API call; archived Feedback is intentionally excluded. | | feedback get | Reads one feedback item's current server snapshot and snapshot_hash. | Read-only; backend checks project access. | | feedback status | Creates a local YAML proposal to change canonical lifecycle state. | No live mutation until submit and owner/delegate review, except owner-direct apply. | | feedback edit / feedback refine | Creates a local YAML proposal for title, description/body, priority, due date, tags, or notes. | Content changes go through owner-review membrane. | | feedback assign | Creates a local YAML proposal to change assignee. | Goes through review unless applied through owner-direct path. | | feedback archive | Creates a local YAML proposal to archive. | Archive is governed by backend owner/delegate capability. | | feedback submit | Sends a local proposal artifact to the backend as a review request. | Does not mutate live feedback before approval. | | feedback revise | Resubmits the original submitter's request after request_changes. | Only valid for the original submitter and needs_changes requests. | | feedback reviews | Lists review requests or fetches one request by --request-id. | Read-only; response includes backend permissions. | | feedback review | Approves, rejects, requests changes, or cancels one review request, or a batch with --request-ids. | Backend restricts approval/review decisions to Project Owner or elevated delegate for Feedback scope; batch review uses one grouped notification path. | | feedback move | Moves a card or batch of cards across allowed board states directly with an audit event. | --feedback-ids sends one batch request. Blocked with pending_feedback_review while an active linked review request exists; governed states such as archive/reject/deploy/freeze remain backend-authorized. Project-key unarchive is not supported. | | feedback undo | Reverses an audited board event when there is no conflict. | Backend validates event ownership/project scope and conflict state. | | feedback prd-versions | Lists retained PRD baselines/revisions for a feedback item. | Read-only; old S3 objects are retained by reference. | | feedback prd-diff | Fetches backend-generated text diff for PRD versions. | Read-only; backend controls version access. | | feedback history | Lists audited feedback board/refinement events. | Read-only; backend checks project access. | | feedback validate | Sends an artifact to backend validation without mutation. | Useful before submit or owner-direct apply. | | feedback apply | Applies an artifact through the owner-direct/emergency path. | Not the normal collaborator flow; normal flow is submit -> review. |

Canonical feedback lifecycle states are frozen, todo, in_progress, in_review, completed, deployed, rejected, and archived.

Reusable live smoke harness after deploy:

node ./scripts/feedback-live-full-harness.js --confirm-live --base-url https://api.myte.dev/api

The harness creates five disposable TEST feedback items from markdown, verifies batch review and batch board movement, batch archives the disposable items, verifies normal feedback-sync excludes archived items, and verifies the project-key surface does not expose Feedback unarchive/restore.

Direct Project API Surface

All routes use Authorization: Bearer <MYTE_API_KEY>. The CLI adds idempotency and client-session headers on mutation routes.

Read/sync routes:

• GET /api/project-assistant/config
• GET /api/project-assistant/bootstrap
• GET /api/project-assistant/qaqc-sync
• GET /api/project-assistant/feedback-sync
• GET /api/project-assistant/feedback/<feedback_id>
• GET /api/project-assistant/feedback/<feedback_id>/refinement/history
• GET /api/project-assistant/feedback-review-requests
• GET /api/project-assistant/feedback-review-requests/<request_id>
• GET /api/project-assistant/feedback/<feedback_id>/events
• GET /api/project-assistant/feedback/<feedback_id>/prd/versions
• GET /api/project-assistant/feedback/<feedback_id>/prd/versions/<version_id>/diff
• GET /api/project-assistant/suggestions
• GET /api/project-assistant/run-qaqc/<batch_id>

Mutation routes:

• POST /api/project-assistant/query
• POST /api/project-assistant/run-qaqc
• POST /api/project-assistant/mission-status-update
• POST /api/project-assistant/mission-archive
• POST /api/project-assistant/project-comment
• POST /api/project-assistant/update-owner
• POST /api/project-assistant/client-update-drafts
• POST /api/project-assistant/create-prd
• POST /api/project-assistant/create-prds
• POST /api/project-assistant/feedback/<feedback_id>/refinement/validate
• POST /api/project-assistant/feedback/<feedback_id>/refinement/requests
• POST /api/project-assistant/feedback-review-requests/<request_id>/revise
• POST /api/project-assistant/feedback/<feedback_id>/refinement/apply
• POST /api/project-assistant/feedback-review-requests/<request_id>/review
• POST /api/project-assistant/feedback-review-requests/batch-review
• POST /api/project-assistant/feedback-review-requests/<request_id>/request-changes
• POST /api/project-assistant/feedback-review-requests/<request_id>/cancel
• POST /api/project-assistant/feedback/<feedback_id>/board-move
• POST /api/project-assistant/feedback/batch-board-move
• POST /api/project-assistant/feedback/<feedback_id>/events/<event_id>/undo
• POST /api/project-assistant/suggestions
• POST /api/project-assistant/suggestions/revise
• POST /api/project-assistant/suggestions/review