@mytegroupinc/myte-core 0.0.24 → 0.0.27

package/README.md

@@ -15,6 +15,7 @@ This package exists so the public wrapper can stay small and versioned cleanly.
 - `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
 
@@ -25,6 +26,109 @@ This package exists so the public wrapper can stay small and versioned cleanly.
 - `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 `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 `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`.
+
+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:
+
+```yaml
+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.
+```
+
+```yaml
+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:
+
+```yaml
+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:
+
+```powershell
+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 |
@@ -72,6 +176,7 @@ 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`