labring
diff --git a/‎.agents/plugins/marketplace.json‎
Lines changed: 1 addition & 1 deletion b/‎.agents/plugins/marketplace.json‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎.planning/PROJECT.md‎
Lines changed: 94 additions & 0 deletions b/‎.planning/PROJECT.md‎
Lines changed: 94 additions & 0 deletions
diff --git a/‎.planning/REQUIREMENTS.md‎
Lines changed: 96 additions & 0 deletions b/‎.planning/REQUIREMENTS.md‎
Lines changed: 96 additions & 0 deletions
diff --git a/‎.planning/ROADMAP.md‎
Lines changed: 135 additions & 0 deletions b/‎.planning/ROADMAP.md‎
Lines changed: 135 additions & 0 deletions
@@ -8,7 +8,7 @@
       "name": "sealos",
       "source": {
         "source": "local",
-        "path": "./"
+        "path": "./plugins/sealos"
       },
       "policy": {
         "installation": "AVAILABLE",
 
@@ -0,0 +1,94 @@
+# Sealos Codex Plugin Installation Upgrade
+
+## What This Is
+
+Sealos Skills is a plugin-first skill pack for deploying projects, connecting Sealos Cloud services, and building Sealos Desktop apps from AI agent workflows. This project improves the Codex plugin installation experience by using `phuryn/pm-skills` as the reference for native Codex marketplace installation copy, then aligning the README and required plugin metadata so Codex users can install and invoke Sealos with fewer decisions.
+
+The work is for developers using Codex CLI or Codex App who want Sealos deployment, database, S3, canvas, and app-builder skills available as a managed plugin.
+
+## Core Value
+
+Codex users can discover, install, and invoke the Sealos plugin through the most native Codex plugin flow, with README instructions and plugin metadata that match the actual repository layout.
+
+## Requirements
+
+### Validated
+
+- ✓ The repository is already a Sealos Skills and Codex plugin package with root `skills/**` as the only skill source — existing
+- ✓ `.codex-plugin/plugin.json` points Codex to `./skills/` and defines the `sealos` plugin identity — existing
+- ✓ `.agents/plugins/marketplace.json` supports local Codex marketplace testing — existing
+- ✓ `scripts/validate-codex-plugin.py` validates the Codex manifest, local marketplace entry, platform registry, and asset paths — existing
+- ✓ The README already documents Sealos deploy, database, S3, canvas, app-builder, and multi-host distribution concepts — existing
+
+### Active
+
+- [ ] Make Codex native marketplace installation the primary Codex install path in `README.md`, following the reference shape from `phuryn/pm-skills`.
+- [ ] Keep `npx plugins add ... --target codex` as a compatible or local install path with clear positioning.
+- [ ] Align Codex install copy with the actual Sealos plugin name, marketplace name, invocation surface, and Codex App selection flow.
+- [ ] Verify `.codex-plugin/plugin.json`, `.agents/plugins/marketplace.json`, `distribution/platforms.json`, and README examples agree after the copy changes.
+- [ ] Run the Codex plugin validator and JSON syntax checks after changing distribution-facing files.
+
+### Out of Scope
+
+- Reworking the deploy, database, S3, canvas, or app-builder skill workflows — this milestone targets install/distribution experience.
+- Creating a second packaged copy of `skills/**` — root `skills/**` remains the only skill source.
+- Redesigning all non-Codex distribution flows — Claude, Gemini, Qwen, CodeBuddy, OpenClaw, and skills.sh paths stay consistent unless touched by Codex wording.
+- Adding new runtime capabilities to Codex plugins — this milestone documents and validates current plugin support.
+
+## Context
+
+The current README recommends `npx plugins add https://github.com/labring/sealos-skills --target codex` as the main Codex install path. The reference project `phuryn/pm-skills` presents Codex installation through native marketplace commands:
+
+```bash
+codex plugin marketplace add phuryn/pm-skills
+codex plugin add pm-toolkit@pm-skills
+```
+
+For Sealos, the comparable target is a single plugin install from the Sealos marketplace rather than many plugin installs. The README should teach the expected Codex path first, then keep `npx plugins` as a fallback or compatibility path. Existing codebase mapping identifies distribution metadata duplication as a fragile area, so any README change must be checked against manifests and validators.
+
+Relevant current files:
+
+- `README.md` — primary install and usage documentation
+- `.codex-plugin/plugin.json` — Codex plugin manifest
+- `.agents/plugins/marketplace.json` — local Codex marketplace entry
+- `distribution/platforms.json` — platform support and evidence registry
+- `scripts/validate-codex-plugin.py` — Codex manifest validator
+- `marketplaces/README.md` — marketplace rules and support-claim ownership
+- `skills/**/SKILL.md` — canonical skill source
+
+## Constraints
+
+- **Single skill source**: Root `skills/**` stays canonical for Codex, skills.sh, and every host manifest — prevents drift across packaged copies.
+- **Codex accuracy**: README commands must match actual Codex plugin naming and repository marketplace behavior — users should be able to follow commands directly.
+- **Support claims**: Codex plugin documentation must reflect current command and skill exposure semantics — prevents overclaiming unsupported slash-command behavior.
+- **Validation**: Distribution-facing changes must pass `python3 scripts/validate-codex-plugin.py` and JSON syntax checks — keeps manifest and registry drift visible.
+- **Scope**: The milestone optimizes install and README experience — deploy/runtime skill behavior stays stable.
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Use `phuryn/pm-skills` as the install-copy reference | It shows Codex native marketplace setup and plain-language Codex differences clearly | — Pending |
+| Prioritize Codex marketplace commands for Codex users | Codex users should see Codex-native commands before cross-host installer syntax | — Pending |
+| Keep `npx plugins add` documented as a compatibility/local path | The repo already supports it and it remains useful for local testing | — Pending |
+| Keep root `skills/**` as the only skill source | Existing architecture depends on one canonical skill tree across hosts | ✓ Good |
+
+## Evolution
+
+This document evolves at phase transitions and milestone boundaries.
+
+**After each phase transition** (via `$gsd-transition`):
+1. Requirements invalidated? → Move to Out of Scope with reason
+2. Requirements validated? → Move to Validated with phase reference
+3. New requirements emerged? → Add to Active
+4. Decisions to log? → Add to Key Decisions
+5. "What This Is" still accurate? → Update if drifted
+
+**After each milestone** (via `$gsd-complete-milestone`):
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state
+
+---
+*Last updated: 2026-06-15 after initialization*
@@ -0,0 +1,96 @@
+# Requirements: Sealos Codex Plugin Installation Upgrade
+
+**Defined:** 2026-06-15  
+**Core Value:** Codex users can discover, install, and invoke the Sealos plugin through the most native Codex plugin flow, with README instructions and plugin metadata that match the actual repository layout.
+
+## v1 Requirements
+
+### Discovery
+
+- [x] **DISC-01**: Maintainer can add this repository as a Codex marketplace in an isolated Codex home.
+- [x] **DISC-02**: Maintainer can list `sealos@sealos` through `codex plugin list --available --json` after adding the marketplace.
+- [x] **DISC-03**: Maintainer can install `sealos@sealos` through `codex plugin add sealos@sealos --json` in an isolated Codex home.
+
+### Documentation
+
+- [x] **DOCS-01**: Codex Quick Start leads with `codex plugin marketplace add labring/sealos-skills`.
+- [x] **DOCS-02**: Codex Quick Start installs the plugin with `codex plugin add sealos@sealos`.
+- [x] **DOCS-03**: README explains that one Sealos plugin installs deploy, database, S3, canvas, app-builder, and supporting cloud-native skills.
+- [x] **DOCS-04**: README keeps `npx plugins add https://github.com/labring/sealos-skills --target codex` as a compatibility or local install path.
+- [x] **DOCS-05**: README uses Codex-specific invocation wording and keeps Claude-compatible `/sealos` examples in Claude-specific sections.
+- [x] **DOCS-06**: README keeps Codex App selection guidance and the existing Sealos plugin screenshot close to the Codex install path.
+
+### Metadata
+
+- [x] **META-01**: Codex-facing metadata consistently uses repo source `labring/sealos-skills`, marketplace id `sealos`, plugin id `sealos`, and display label `Sealos`.
+- [x] **META-02**: `.codex-plugin/plugin.json` remains aligned with README Codex plugin identity, display copy, asset paths, and root `./skills/` source.
+- [x] **META-03**: `marketplace.json`, `.claude-plugin/marketplace.json`, and `.agents/plugins/marketplace.json` expose the installable Sealos plugin without duplicating `skills/**`.
+- [x] **META-04**: `distribution/platforms.json` records the verified Codex native install path, fallback install path, invocation wording, evidence, and verification date.
+
+### Validation
+
+- [x] **VAL-01**: `scripts/validate-codex-plugin.py` checks README native Codex install commands.
+- [x] **VAL-02**: `scripts/validate-codex-plugin.py` checks README fallback `npx plugins` command.
+- [x] **VAL-03**: `scripts/validate-codex-plugin.py` checks README/manifest/registry plugin identity parity.
+- [x] **VAL-04**: JSON syntax checks pass for all touched plugin, marketplace, and platform registry files.
+
+### Handoff
+
+- [x] **HAND-01**: Final verification includes isolated Codex native marketplace add, list, and install smoke output.
+- [x] **HAND-02**: Final verification includes compatibility install or discovery evidence for the `npx plugins` path.
+- [x] **HAND-03**: Final handoff reports the exact files changed and any remaining non-Codex distribution follow-up.
+
+## v2 Requirements
+
+### Distribution
+
+- **DIST-01**: Add a distribution-wide validator covering Claude, CodeBuddy, Gemini, Qwen, OpenClaw, marketplace, and command-route parity with root `skills/**`.
+- **DIST-02**: Add CI or a documented local command that runs all distribution validators.
+- **DIST-03**: Refresh non-Codex install screenshots or GIFs if host UI copy changes.
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Deploy skill behavior changes | Current milestone targets installation and README distribution experience. |
+| Database, S3, canvas, or app-builder workflow changes | These capabilities are installed by the plugin but their runtime behavior is stable scope. |
+| Host-specific skill copies | Root `skills/**` is the canonical source and duplicate copies create drift. |
+| Full non-Codex distribution migration | Claude, Gemini, Qwen, CodeBuddy, OpenClaw, and skills.sh are secondary unless Codex wording creates a direct inconsistency. |
+| New product screenshots | Existing Codex App screenshot is sufficient for this milestone unless verification shows it has become misleading. |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| DISC-01 | Phase 1 | Complete |
+| DISC-02 | Phase 1 | Complete |
+| DISC-03 | Phase 1 | Complete |
+| DOCS-01 | Phase 2 | Complete |
+| DOCS-02 | Phase 2 | Complete |
+| DOCS-03 | Phase 2 | Complete |
+| DOCS-04 | Phase 2 | Complete |
+| DOCS-05 | Phase 2 | Complete |
+| DOCS-06 | Phase 2 | Complete |
+| META-01 | Phase 2 | Complete |
+| META-02 | Phase 2 | Complete |
+| META-03 | Phase 1 | Complete |
+| META-04 | Phase 2 | Complete |
+| VAL-01 | Phase 3 | Complete |
+| VAL-02 | Phase 3 | Complete |
+| VAL-03 | Phase 3 | Complete |
+| VAL-04 | Phase 3 | Complete |
+| HAND-01 | Phase 4 | Complete |
+| HAND-02 | Phase 4 | Complete |
+| HAND-03 | Phase 4 | Complete |
+
+**Coverage:**
+
+- v1 requirements: 20 total
+- Mapped to phases: 20
+- Unmapped: 0
+
+---
+*Requirements defined: 2026-06-15*
+*Last updated: 2026-06-15 after roadmap creation*
@@ -0,0 +1,135 @@
+# Roadmap: Sealos Codex Plugin Installation Upgrade
+
+## Overview
+
+This MVP upgrades the Sealos Codex plugin install experience from a compatibility-first path to a Codex-native marketplace path, then aligns README copy, metadata claims, validator coverage, and install smoke evidence around one installable plugin: `sealos@sealos`.
+
+## Phases
+
+**Phase Numbering:**
+
+- Integer phases (1, 2, 3): Planned milestone work
+- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+Decimal phases appear between their surrounding integers in numeric order.
+
+- [x] **Phase 1: Native Marketplace Discovery Contract** - Prove the Sealos repository exposes an installable `sealos@sealos` plugin through Codex native marketplace discovery. (completed 2026-06-15)
+- [x] **Phase 2: README and Metadata Alignment** - Make the verified native path the primary Codex install story and align metadata, registry claims, and invocation wording. (completed 2026-06-15)
+- [x] **Phase 3: Validator Hardening** - Extend validation so README commands, fallback install copy, plugin identity, and JSON syntax drift fail loudly. (completed 2026-06-15)
+- [x] **Phase 4: Install Smoke and Handoff** - Capture native and compatibility install evidence, then hand off the exact changed files and remaining follow-up. (completed 2026-06-15)
+
+## Phase Details
+
+### Phase 1: Native Marketplace Discovery Contract
+
+**Goal:** Maintainers can add this repository as a Codex marketplace and install `sealos@sealos` from an isolated Codex environment.
+**Mode:** mvp
+**Depends on:** Nothing (first phase)
+**Requirements:** DISC-01, DISC-02, DISC-03, META-03
+**Success Criteria** (what must be TRUE):
+
+  1. Maintainer can add the repository as a Codex marketplace in an isolated `HOME` and `CODEX_HOME`.
+  2. Maintainer can see `sealos@sealos` in `codex plugin list --available --json`.
+  3. Maintainer can install `sealos@sealos` with `codex plugin add sealos@sealos --json`.
+  4. Marketplace metadata exposes the installable Sealos plugin while root `skills/**` remains the single canonical skill source.
+
+**Plans:** 3/3 plans complete
+
+### Phase 2: README and Metadata Alignment
+
+**Goal:** Codex users see a README and metadata contract that teaches the verified native install path, compatibility path, installed capabilities, and correct invocation surface.
+**Mode:** mvp
+**Depends on:** Phase 1
+**Requirements:** DOCS-01, DOCS-02, DOCS-03, DOCS-04, DOCS-05, DOCS-06, META-01, META-02, META-04
+**Success Criteria** (what must be TRUE):
+
+  1. Reader sees `codex plugin marketplace add labring/sealos-skills` before the plugin install command in the Codex Quick Start.
+  2. Reader sees `codex plugin add sealos@sealos` as the native Codex plugin install command.
+  3. Reader understands that one Sealos plugin installs deploy, database, S3, canvas, app-builder, and supporting cloud-native skills.
+  4. Reader sees `npx plugins add https://github.com/labring/sealos-skills --target codex` as the compatibility or local install path.
+  5. Reader sees Codex-specific invocation and Codex App selection guidance near the Sealos plugin screenshot, while Claude-compatible command examples remain in Claude-specific sections.
+
+**Plans:** 2/2 plans complete
+
+Plans:
+
+- [x] 02-01-PLAN.md — Align README Codex native install, compatibility path, capabilities, and invocation wording.
+- [x] 02-02-PLAN.md — Align Codex platform metadata and run existing validation gates.
+
+### Phase 3: Validator Hardening
+
+**Goal:** Maintainers can run validation that catches README, manifest, marketplace, platform registry, fallback install, and JSON syntax drift.
+**Mode:** mvp
+**Depends on:** Phase 2
+**Requirements:** VAL-01, VAL-02, VAL-03, VAL-04
+**Success Criteria** (what must be TRUE):
+
+  1. `scripts/validate-codex-plugin.py` fails when README native Codex install commands are absent or mismatched.
+  2. `scripts/validate-codex-plugin.py` fails when the README fallback `npx plugins` command is absent or mismatched.
+  3. `scripts/validate-codex-plugin.py` fails when README, manifest, marketplace, or platform registry plugin identity diverges.
+  4. JSON syntax checks pass for every touched plugin, marketplace, and platform registry file.
+
+**Plans:** 1/1 plans complete
+
+Plans:
+
+- [x] 03-01-PLAN.md — Harden the Codex validator for README commands, fallback install, identity parity, platform registry fields, JSON syntax coverage, and targeted drift-failure proof.
+
+### Phase 4: Install Smoke and Handoff
+
+**Goal:** Maintainers finish the milestone with native install evidence, compatibility install evidence, and a clear changed-file handoff.
+**Mode:** mvp
+**Depends on:** Phase 3
+**Requirements:** HAND-01, HAND-02, HAND-03
+**Success Criteria** (what must be TRUE):
+
+  1. Final verification records isolated Codex native marketplace add, available-list, and install smoke output.
+  2. Final verification records compatibility install or discovery evidence for the `npx plugins` path.
+  3. Final handoff reports the exact files changed during the milestone.
+  4. Final handoff names any remaining non-Codex distribution follow-up.
+
+**Plans:** 2/2 plans complete
+
+Plans:
+
+- [x] 04-01-PLAN.md — Capture isolated native Codex install smoke evidence and native payload assertions.
+- [x] 04-02-PLAN.md — Capture compatibility evidence, aggregate assertions, cleanup proof, validation transcript, and final changed-file handoff.
+
+## Requirement Coverage
+
+| Requirement | Phase |
+|-------------|-------|
+| DISC-01 | Phase 1 |
+| DISC-02 | Phase 1 |
+| DISC-03 | Phase 1 |
+| DOCS-01 | Phase 2 |
+| DOCS-02 | Phase 2 |
+| DOCS-03 | Phase 2 |
+| DOCS-04 | Phase 2 |
+| DOCS-05 | Phase 2 |
+| DOCS-06 | Phase 2 |
+| META-01 | Phase 2 |
+| META-02 | Phase 2 |
+| META-03 | Phase 1 |
+| META-04 | Phase 2 |
+| VAL-01 | Phase 3 |
+| VAL-02 | Phase 3 |
+| VAL-03 | Phase 3 |
+| VAL-04 | Phase 3 |
+| HAND-01 | Phase 4 |
+| HAND-02 | Phase 4 |
+| HAND-03 | Phase 4 |
+
+**Coverage:** 20/20 v1 requirements mapped.
+
+## Progress
+
+**Execution Order:**
+Phases execute in numeric order: 1 -> 2 -> 3 -> 4
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. Native Marketplace Discovery Contract | 3/3 | Complete    | 2026-06-15 |
+| 2. README and Metadata Alignment | 2/2 | Complete    | 2026-06-15 |
+| 3. Validator Hardening | 1/1 | Complete    | 2026-06-15 |
+| 4. Install Smoke and Handoff | 2/2 | Complete    | 2026-06-15 |