diff --git a/.agents/skills/cli-guide/SKILL.md b/.agents/skills/cli-guide/SKILL.md new file mode 100644 index 0000000..67923d7 --- /dev/null +++ b/.agents/skills/cli-guide/SKILL.md @@ -0,0 +1,65 @@ +--- +name: cli-guide +description: Navigate and change the MiniMax Code command tree, interactive TUI, headless exec, ACP adapters, or their in-process runtime connection. Use when implementing or debugging CLI behavior in this repository. +--- + +# CLI Architecture Guide + +Read `docs/architecture.md` and the current command registration before proposing +a change. The standalone entry point lives in `packages/tui`. + +## Entry points + +| Path | Responsibility | +| --- | --- | +| `packages/tui/src/index.ts` | Process bootstrap and runtime environment | +| `packages/tui/src/cli/main.ts` | Command execution and process lifecycle | +| `packages/tui/src/cli/program.ts` | Commander command registration | +| `packages/tui/src/cli/contract.ts` | Interactive and exec option contracts | +| `packages/tui/src/tui/` | Interactive terminal UI | +| `packages/tui/src/headless/` | Exec invocation, output, cancellation and settlement | +| `packages/tui/src/acp/` | ACP protocol adapter | +| `packages/tui/src/runtime/adapter.ts` | Adapter to the in-process CliService | +| `packages/local-runtime-v2/src/local/` | Local product service entry points | +| `packages/protocol/src/local.ts` | Shared CLI data structures | + +The execution path is: + +```text +TUI / exec / ACP + -> CliService + -> local applications + -> session / turn / agent services + -> model providers and tools +``` + +Preserve that in-process boundary. Shared behavior belongs in the relevant +application or service; presentation and transport behavior belong in their +adapters. Trace callers before assuming a fix to one adapter covers the others. + +## Implementing changes + +- For commands and flags, inspect `cli/program.ts`, `cli/contract.ts`, and the + affected command handler together. Check parsing, help, dispatch and errors. +- For interactive behavior, follow the controller and rendering path under + `tui/`. Check session selection, queued input and interruption where affected. +- For exec, follow invocation through output and settlement. Verify stdout, + stderr, exit code and cancellation; help output alone is insufficient. +- For ACP, check protocol updates and the underlying runtime operation together. +- For shared runtime changes, identify all affected TUI, exec and ACP consumers. + +## Verification + +Use [testing-workflow](../testing-workflow/SKILL.md) to select declared tests. +Build the standalone artifact before inspecting its actual help: + +```bash +pnpm build +node dist/cli.js --help +node dist/cli.js exec --help +node dist/cli.js acp --help +``` + +Read current help before documenting flags. Use temporary data directories and +synthetic inputs for behavior checks, following the existing smoke/BYOK tests. +Report offline protocol tests separately from live-provider acceptance. diff --git a/.agents/skills/cross-layer-drift-sweep/SKILL.md b/.agents/skills/cross-layer-drift-sweep/SKILL.md new file mode 100644 index 0000000..0a88b73 --- /dev/null +++ b/.agents/skills/cross-layer-drift-sweep/SKILL.md @@ -0,0 +1,58 @@ +--- +name: cross-layer-drift-sweep +description: Check completed cross-layer changes for stale fields, defaults, types, contracts or wording across storage, runtime, adapters, TUI and documentation. Use after a rename or contract change with downstream consumers, not for unrelated single-file edits. +--- + +# Cross-Layer Drift Sweep + +Type checking can miss manual mappings, serialized fields and assertions hidden +behind casts. Sweep the narrow data flow affected by the change before reporting +completion. + +## Establish the change + +Record the change axis: type narrowing, field rename, configuration default, +contract evolution or display wording. Name the old and new expressions and the +producer and final observable consumer. + +Draw the relevant flow, for example: + +```text +storage -> runtime writer -> local service -> adapter -> TUI / exec / ACP -> docs +``` + +Only include layers that actually consume the changed value. + +## Sweep + +1. Search both old and new expressions. Include source, comments, tests, + fixtures, snapshots and relevant documentation. Paired searches reveal layers + that adopted only part of a change. +2. Check the likely gaps for the change axis: + + | Axis | Common gaps | + | --- | --- | + | Type narrowing | Runtime writers, filesystem reads with casts, serializers, adapter mappings | + | Field rename | Schema, migrations, inline test DDL, fixtures, mappings, user-visible labels | + | Configuration default | Defaults, thresholds, examples, logs, status output and documentation | + | Contract evolution | Local protocol types, service exports, call sites and compatibility fixtures | + | Display wording | TUI, exec output, logs, screenshots and exact-string assertions | + +3. Fix mismatches within the changed data flow. Explain deliberate compatibility + remnants in an adjacent comment or regression test. Avoid changing unrelated + matches merely because they contain the same token. +4. Verify an assertion at the final observable layer, such as rendered text, + serialized output, a local-service result or a database-backed read. Reuse an + existing assertion when it already covers the behavior; add one when there is + a meaningful regression gap. +5. Run affected tests and type checks using + [testing-workflow](../testing-workflow/SKILL.md). For runtime inputs with + alternate paths or caches, also use + [verify-all-runtime-sinks](../verify-all-runtime-sinks/SKILL.md). + +## Evidence + +Report the axis, data flow, old/new search terms, layers checked, mismatches fixed +and verification results. Explain remaining old-token matches. If the final +consumer could not be exercised, state the gap and the nearest contract evidence +instead of treating a parser-only test as complete validation. diff --git a/.agents/skills/retro/SKILL.md b/.agents/skills/retro/SKILL.md new file mode 100644 index 0000000..bba2861 --- /dev/null +++ b/.agents/skills/retro/SKILL.md @@ -0,0 +1,50 @@ +--- +name: retro +description: Extract evidence-backed lessons from a completed development session and propose focused improvements to repository guidance. Use when the user asks for a retrospective or to capture reusable lessons. +--- + +# Session Retrospective + +Turn concrete failures, retries and workflow gaps into a small set of reusable +improvements. Do not turn one-off preferences into repository-wide rules. + +## Review the evidence + +For each useful lesson, record: + +- **Event:** what happened, with a public-safe file, command, error or commit. +- **Cause:** the demonstrated reason, separated from hypotheses. +- **Lesson:** what a future contributor should do differently. +- **Impact:** safety/data, correctness, efficiency or preference. + +Skip unsupported opinions and one-off circumstances. Combine duplicate lessons +and keep the result focused on the few changes that would prevent recurrence. +Redact credentials, private service details and real user content from evidence. + +## Find the right home + +Read existing guidance before proposing additions: + +| Lesson | Candidate location | +| --- | --- | +| Repository-wide constraint | `AGENTS.md` or `CONTRIBUTING.md` | +| A specific reusable workflow | The relevant `.agents/skills` entry | +| Build, release or source-sync procedure | The relevant document under `docs/` | +| A behavioral defect | A focused code fix and regression test proposal | + +Prefer correcting an existing instruction over introducing a parallel process +or a new notes/proposals directory. Check current source and scripts before +preserving an explanation that might already be stale. + +## Scope and delivery + +If the user asks only for a retrospective, return the findings and proposed +edits. Apply documentation changes when requested, within the established scope. +Do not treat the retrospective as authorization to create issues, send messages, +publish changes or modify personal/agent memory. Write memory only when the user +explicitly asks for that persistence and the environment supports it. + +For applied changes, keep public contributor guidance in English. New files +require publication review and inventory regeneration; content-only changes do +not. Report the lessons, evidence, proposed or applied destinations, checks run +and remaining decisions. diff --git a/.agents/skills/testing-workflow/SKILL.md b/.agents/skills/testing-workflow/SKILL.md new file mode 100644 index 0000000..cf44573 --- /dev/null +++ b/.agents/skills/testing-workflow/SKILL.md @@ -0,0 +1,67 @@ +--- +name: testing-workflow +description: Select and report verification for MiniMax Code changes using the repository's declared test suites and CI gates. Use when validating code, skills, documentation, build tooling or source-distribution changes. +--- + +# Testing Workflow + +Start with changed files, then identify the owning runtime, user entry point and +final observable behavior. Read `AGENTS.md`, `CONTRIBUTING.md` and the applicable +steps in `scripts/verify.mjs`. + +## Focused iteration + +Vitest files belong to groups in `test/vitest-suites.json`; aliases and inclusion +come from `vitest.oss.config.mjs`. Select an existing declared file for a focused +run, for example: + +```bash +pnpm exec vitest run --config vitest.oss.config.mjs packages/tui/test/unit/headless-contract.test.ts +``` + +Register new Vitest files in the suite declaration. Do not add hard-coded file +lists to package scripts or the Vitest configuration. Vendored upstream test +suites are outside this distribution's verification. + +| Scope | Repository gate | +| --- | --- | +| Runtime, TUI, providers, plugins and ACP | `pnpm test:capabilities` | +| Headless CLI and offline BYOK behavior | `pnpm test:byok` | +| CLI artifact smoke | `pnpm test:smoke` | +| Public artifact content | `pnpm test:artifact` | +| TUI build-mode contract | `pnpm test:status-contract` | +| Permission facade on macOS/Linux | `pnpm test:policy` | +| Sandbox on macOS | `pnpm test:sandbox` | +| Source-sync, workflow and release tools | `pnpm test:release-tools` | +| Types and standalone build boundary | `pnpm typecheck`, `pnpm build`, `pnpm check:standalone` | +| Published files and generated paths | `pnpm check:source`, `pnpm check:tsconfig` | + +Artifact-dependent tests require a current `pnpm build`. Keep test state and +reports outside the repository, using synthetic data and temporary directories. + +## Delivery verification + +Run `git diff --check` and the relevant individual gates while editing. Review +new or removed files before regenerating `release/public-source.json` with +`node scripts/source-inventory.mjs --write`. + +Before opening a PR, run `pnpm verify` on the reviewed commit with a clean tracked +working tree. Source export reads committed HEAD and rejects uncommitted tracked +changes; report that limitation if only iteration checks are possible. + +Use `pnpm verify --list` to inspect the current platform's gates. Use the `docs` +profile only when every changed path qualifies under `scripts/ci-changes.mjs`. +Skills under `.agents/skills`, unknown paths and inventory changes require the +full profile. The `archive` profile is for source-archive validation, not a way to +bypass the clean-commit export requirement. + +## Manual evidence and reporting + +For CLI behavior, exercise the built `dist/cli.js` and inspect stdout, stderr and +exit code. For terminal presentation, exercise the relevant interaction when +feasible. For provider or service changes, distinguish offline fixtures from a +real endpoint call. + +Report scope, commands and results, manual scenarios, and untested boundaries. +Use PASS/FAIL/BLOCKED for actual checks; mark checks that did not run explicitly. +Local macOS success does not establish Windows/Linux or live-service acceptance. diff --git a/.agents/skills/verify-all-runtime-sinks/SKILL.md b/.agents/skills/verify-all-runtime-sinks/SKILL.md new file mode 100644 index 0000000..0a59f2a --- /dev/null +++ b/.agents/skills/verify-all-runtime-sinks/SKILL.md @@ -0,0 +1,56 @@ +--- +name: verify-all-runtime-sinks +description: Verify that runtime-affecting schema, prompt, identity, adapter, cache or rename changes reach every affected consumer. Use before declaring runtime validation complete when alternate entry points or persisted/generated values can retain old behavior. +--- + +# Verify All Runtime Sinks + +Identify where a changed value is finally consumed, beyond its first parser or +happy-path test. This skill defines where to verify; use +[testing-workflow](../testing-workflow/SKILL.md) for commands and gates. + +## Procedure + +1. Name the changed contract, field, prompt, identity or adapter behavior. Identify + the producer and final runtime consumer, and describe the stale behavior that + a partial change would leave behind. +2. Map the affected consumers. Mark each dimension `covered`, `not applicable` + or `unknown`, with a reason: + - **Parser to runtime:** normalized objects, managers, launch options, + serialization boundaries and service inputs. + - **Alternate entry points:** TUI, exec, ACP, task/session launches, built-in + and project agents, and explicit historical-data importers where relevant. + - **Generated or cached values:** bundled prompts, static prompt caches, + compiled configuration, persisted state and memoized objects. + - **Fixtures and artifacts:** tests, snapshots, example agents/skills and + built distribution assets when affected. + - **String remnants:** old property names, environment/configuration keys, + log labels and documentation used by generation or tests. +3. Search for both old and new tokens beyond source files. Include ignored build + outputs explicitly when checking artifacts; an ordinary repository search may + skip them. Inspect raw serialized shapes where types or casts can hide drift. +4. Exercise the affected runtime paths through their final consumers. Check each + adapter that can bypass the tested path. Shared implementation is evidence + only after tracing how those adapters reach it. For prompts, check source + selection and caching; for identity/schema changes, check agent kinds that + parse differently. +5. Record commands, results, remaining old-token hits and compatibility reasons. + Inspect or regenerate caches using isolated test state; do not clear a user's + sessions or configuration as part of verification. + +## Completion bar + +Do not declare complete runtime coverage while a relevant consumer is `unknown` +or an unexplained old value remains. Report narrower passing checks and the +remaining gap. Parser tests alone do not establish propagation through launch, +execution and final presentation. + +Example evidence: + +```text +Parser to service: covered by the affected integration test. +Exec and ACP: covered by adapter tests; interactive TUI: not run. +Prompt cache: not applicable; the changed value is not cached. +Old field: retained only in the historical importer and its fixture. +Result: focused checks pass; interactive acceptance remains unverified. +``` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fbaade5..3e4adf0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,6 +18,20 @@ Preserve original third-party license text. Localized product strings, multiling ## Local validation +Repository development skills are available under [`.agents/skills`](.agents/skills): + +| Skill | Use | +| --- | --- | +| [cli-guide](.agents/skills/cli-guide/SKILL.md) | Navigate TUI, exec, ACP and their runtime boundary | +| [cross-layer-drift-sweep](.agents/skills/cross-layer-drift-sweep/SKILL.md) | Check renames, defaults and contracts across consumers | +| [testing-workflow](.agents/skills/testing-workflow/SKILL.md) | Select focused checks and the required delivery gates | +| [verify-all-runtime-sinks](.agents/skills/verify-all-runtime-sinks/SKILL.md) | Verify alternate runtime paths, caches and artifacts | +| [retro](.agents/skills/retro/SKILL.md) | Turn demonstrated failures into focused guidance improvements | + +These are contributor workflows, separate from bundled product skills. They are +adapted to this distribution's paths and verification contracts; workflow changes +should update the relevant skill alongside its source of truth. + ```bash pnpm install --frozen-lockfile pnpm verify diff --git a/release/public-source.json b/release/public-source.json index b9c1ff4..dcc0a66 100644 --- a/release/public-source.json +++ b/release/public-source.json @@ -1,6 +1,11 @@ { "schemaVersion": 1, "files": [ + ".agents/skills/cli-guide/SKILL.md", + ".agents/skills/cross-layer-drift-sweep/SKILL.md", + ".agents/skills/retro/SKILL.md", + ".agents/skills/testing-workflow/SKILL.md", + ".agents/skills/verify-all-runtime-sinks/SKILL.md", ".gitattributes", ".github/CODEOWNERS", ".github/ISSUE_TEMPLATE/01-bug-report.yml",