Skip to content

README.md

Latest commit

 

History

History
190 lines (129 loc) · 16.9 KB

README.md

File metadata and controls

190 lines (129 loc) · 16.9 KB
Raw

Svif Plugin

This directory is the portable Svif Plugin package.

It targets Agent Plugins 1.0.0 and intentionally starts with a Skill-only MVP. The repository also carries OpenAI/Codex distribution metadata without replacing the portable package contract:

svif/
├── .agents/plugins/marketplace.json
└── plugin/
    ├── plugin.json
    ├── .codex-plugin/plugin.json
    ├── assets/svif-directory-icon.png
    └── skills/
        └── svif/
            └── SKILL.md

plugin/plugin.json is the canonical Agent Plugins 1.0 portable manifest and carries current OpenAI listing metadata under extensions.com.openai. plugin/.codex-plugin/plugin.json remains a synchronized compatibility fallback for clients that still read the Codex overlay. Neither manifest may introduce a second Orchestrator or a second continuity source of truth.

A Skill-only Plugin is structurally useful without an MCP server. MCP packaging can be added later without changing the Svif product kernel or durable Project-continuity model.

Local acceptance before publication

OpenAI Platform submission is paused by the Principal. Current 0.2.0 is an unpublished local-readiness candidate; prior ZIP/CI acceptance is not functional release sign-off. The native local procedure and requirement-to-evidence matrix are maintained in conformance/RELEASE_READINESS.md in the source repository. Keep the user install intent short; the maintainer acceptance harness owns isolated installation and exact-revision checks. A local marketplace does not require public Platform publication.

The Skill requires trusted verification and provider-owned authority policy, contained reads/writes and coherent recovery. It must block on unresolved .svif-runtime recovery markers when encountering a Project previously operated by the Python adapter. This package contains instructions, not that runtime or a remote MCP service.

Current validation status

Repository CI validates the portable package structure, Agent Plugins 1.0.0 manifest constraints used by this package, Agent Skills frontmatter/guardrails, Plugin-root filesystem containment and component isolation, Agnir activation/discovery guards, OpenAI/Codex distribution metadata, public-directory listing limits, required square logo / composerIcon branding assets, and the boundary that prevents the Plugin from shadowing the Svif runtime.

Current main carries the unpublished 0.2.0 public-submission candidate. The already released Repository Preview remains immutable as v0.2.0-preview.1; these are distinct versioned subjects.

That is package/conformance/distribution validation, not proof that a particular ChatGPT, Codex, or other compatible client has installed and exercised this exact revision. Repository success does not prove that the Plugin has passed OpenAI public review, appeared in the universal Plugins Directory, been installed by a personal ChatGPT user, or reached a real Project checkpoint.

What this MVP does

The bundled svif Skill guides a compatible execution surface to:

  • preserve an existing Agnir Project's declared Core/profile compatibility and bind Svif to that exact line instead of silently migrating it;
  • for a genuinely uninitialized Project, resolve the canonical latest published stable Agnir, use the Core/profile declared by that release, and never substitute moving main, an RC, or the historical 0.1 bootstrap baseline;
  • require the version-appropriate durable activation route before normal Project work: current stable packaging uses Project root -> AGENTS.md -> AGNIR.md -> AGNIR.yaml -> durable memory, while supported legacy Projects may retain Project root -> AGENTS.md -> README.md / Agnir Project Instructions -> AGNIR.yaml -> durable memory;
  • validate Agnir Core/profile compatibility and selected-Project identity before loading durable memory;
  • surface unsupported-version, Project-mismatch, authorization, locator, cycle, stale, and inconsistency failures instead of silently falling back to unrelated state;
  • load current state and next actions first, then only relevant decisions/evidence;
  • execute the Svif lifecycle rather than merely describe it;
  • preserve exact-subject verification and provenance across external effects;
  • keep protected authority outside untrusted model/result payloads;
  • independently observe external effects before checkpointing success;
  • write explicit, resumable Current State / Next Actions / Decisions / Evidence checkpoints;
  • stop rather than invent Project state when activation/discovery fails.

The Plugin is a distribution/workflow layer. It does not reimplement src/svif/runtime.py and it does not make ChatGPT or another plugin client authoritative Project memory.

Public personal-ChatGPT distribution

The primary ChatGPT audience for Svif is individual/personal ChatGPT users. The mature consumer path is therefore the universal Plugins Directory, not a managed-workspace GitHub marketplace import.

Current OpenAI developer documentation explicitly allows a public Plugin submission to be Skills only. Svif does not need an MCP server or Apps SDK integration merely to qualify for public Plugin review. The canonical public package is the portable Plugin root: root plugin.json, skills/, and packaged assets. OpenAI-specific listing metadata lives in plugin.json -> extensions.com.openai; .codex-plugin/plugin.json remains a compatibility fallback. MCP remains an optional future capability increment rather than a publication prerequisite.

The current public publishing flow is:

  1. Use an OpenAI Platform organization whose submitter has Apps Management: Write permission; organization owners already have the required submission permission.
  2. Complete a verified individual developer identity or verified business identity in that same OpenAI Platform organization.
  3. Open the OpenAI plugin submission portal and choose Create plugin -> Skills only.
  4. Upload the final portable Plugin root with tested plugin.json, skills/, and assets; retain the synchronized .codex-plugin/plugin.json compatibility fallback. Do not add apps, .app.json, mcpServers, or .mcp.json to a Skills-only submission.
  5. Complete the public listing metadata, starter prompts, review test cases, country/region availability, release notes, and policy attestations.
  6. Submit for review. Submission is not publication.
  7. After OpenAI approves the Plugin, explicitly publish the approved version from the portal.
  8. Only after publication should Svif be expected to appear in the universal Plugins Directory shared by ChatGPT and Codex. Confirm publication by searching the exact publication name or using the directory URL exposed by the submission portal; main-page featuring is separate from publication.

The current .codex-plugin/plugin.json is intentionally kept inside OpenAI's final-directory listing limits used by Svif: displayName <= 30 characters, shortDescription <= 30 characters, longDescription <= 4,000 characters, developerName <= 80 characters, no more than 20 capabilities, and no more than three starter prompts with each prompt <= 128 characters and no @mention. Repository tests guard these limits.

For a Skills-only public submission, OpenAI's current final-directory validation treats website/support/privacy/terms URLs as optional for ZIP uploads. Svif treats them as optional validation fields but recommended publisher material when the portal requests listing/contact information. A verified developer or business identity and skill safety/security scans remain required. If Svif later adds MCP, the submission type and review requirements become materially broader; do not silently treat that as the same release surface.

Proposed public listing

  • Name: Svif
  • Package name: svif
  • Developer: iorLab (subject to the verified publisher identity selected in the portal)
  • Category: Developer Tools
  • Short description: Durable project orchestration
  • Long description: Continue a durable Svif Project through Agnir continuity, explicit verification, trusted authority boundaries, independent observation, and resumable checkpointing without moving canonical Project truth into the execution surface.
  • Starter prompt: Continue this Project using its durable state, implement the next action, verify the result, and checkpoint when finished.
  • Logo / composer icon: plugin/assets/svif-directory-icon.png — byte-identical to the Principal-approved square brand/exports/svif-favicon-128.png (128×128). Both interface.logo and interface.composerIcon point to this package-local asset.
  • Website: https://github.com/iorLab/svif
  • Support / privacy / terms: optional under current Skills-only ZIP final validation; if supplied, use public HTTPS URLs consistent with the verified publisher identity.
  • Availability: choose intended countries/regions explicitly in the submission portal; repository defaults do not broaden availability.
  • Release notes (candidate): Svif 0.2.0 is the first public Skills-only release candidate for durable Project orchestration, preserving Agnir continuity, verification, authority boundaries, independent observation, and checkpoint/resume semantics validated by the Repository Preview.

Review test cases to enter in the submission portal

OpenAI currently asks for five positive and three negative review cases. These cases should be exercised against reviewer-readable fixture Projects rather than relying on private conversation context.

Positive cases

  1. Resume a valid Agnir Project. Prompt: continue the Project and implement the next concrete action. Expected: follow the Project's installed version-appropriate Agnir activation route (AGENTS.md -> AGNIR.md -> AGNIR.yaml for current stable packaging, or the compatible legacy README route when the Project already declares it), validate compatibility/identity, load Current State + Next Actions, perform the concrete work, verify it, and checkpoint durable state.
  2. Checkpoint a non-effectful repository change. Expected: run DISCOVER -> PLAN -> CHANGE -> VERIFY -> CHECKPOINT without inventing DELIVER/OBSERVE evidence.
  3. Repair a missing Agnir locator without destroying existing instructions. Expected: preserve unrelated AGENTS.md content, add only the minimal locator when authorized, rerun activation, and remain idempotent on a second pass.
  4. Resume after a prior checkpoint. Expected: a fresh execution context reconstructs required Project truth from Project-owned durable surfaces rather than conversation memory.
  5. Handle a verified external-effect fixture. Expected: require exact-subject verification and trusted authority, actuate only the verified subject through the available capability boundary, independently observe the resulting target, then checkpoint success.

Negative cases

  1. Missing/ambiguous Agnir discovery. Expected: surface the discovery blocker and stop; do not search sibling Projects or chat history for substitute state.
  2. Project identity or compatibility mismatch. Expected: preserve the explicit Agnir failure class and do not load/checkpoint the mismatched Project state.
  3. External effect without trusted authority or independent observation. Expected: do not actuate when authority is absent; if observation is unavailable or mismatched, do not checkpoint the effect as successful.

These are submission materials, not evidence that OpenAI review has occurred. The portal submission, automated skill scan, reviewer outcome, approval, publication, and real personal-ChatGPT installation are all external observations that must be recorded separately.

Portable package exercise

For an Agent Plugins 1.0 implementation or local conformance harness, plugin/ is the portable package root. This statement describes package layout only; it is not a universal installation instruction for ChatGPT or Codex.

A useful workflow request after a client has actually loaded the Plugin or contained Skill is:

Continue this Project using its durable state, implement the next action, verify the result, and checkpoint when finished.

Expected behavior: the executor follows Project-owned Agnir activation/discovery, performs actionable Project work with verification, distinguishes package success from external-effect success, and persists a resumable checkpoint rather than relying on conversation memory.

Repository Preview self-distribution

v0.2.0-preview.1 remains the immutable self-distributed Skills-only Repository Preview for Codex CLI and ChatGPT desktop/Codex. Current main is the separate, unpublished 0.2.0 public-submission candidate. It uses the repository marketplace and remains separate from the universal Plugins Directory. ChatGPT Web and mobile cannot install this repository Preview through a prompt alone.

The user-facing install intent stays deliberately short:

Install and enable Svif for this Project: https://github.com/iorLab/svif

The installer—not the user prompt—owns the following procedure:

  1. Confirm that the active surface can install repository Plugins. The supported Preview surfaces are Codex CLI and ChatGPT desktop/Codex. If repository Plugin installation is unavailable, report the unsupported surface and do not claim installation succeeded.

  2. Resolve the current published Repository Preview to immutable tag v0.2.0-preview.1. Never silently substitute moving main for a released Preview.

  3. Register the repository marketplace at that exact tag:

    codex plugin marketplace add iorLab/svif --ref v0.2.0-preview.1

  4. In Codex CLI, open /plugins, select the svif marketplace, install and enable Svif, then start a new session. In ChatGPT desktop/Codex, refresh or restart after registering the marketplace, install Svif from the Plugins directory source, then start a new chat.

  5. Continue the user's original Project task after installation. Do not require manual Agnir pre-initialization; the shared Skill owns first-use classification, bootstrap, verification, and checkpoint behavior.

  6. Record the observed surface, installation state, and accepted revision when the client exposes it. Package validation or marketplace registration alone is not installation evidence.

Both supported surfaces reuse the same repository distribution shape:

  • repository: https://github.com/iorLab/svif;
  • marketplace manifest: .agents/plugins/marketplace.json;
  • marketplace source entry: local ./plugin relative to the marketplace root;
  • OpenAI/Codex Plugin manifest: plugin/.codex-plugin/plugin.json;
  • shared Skill implementation: plugin/skills/svif/SKILL.md.

For candidate verification before the immutable Preview tag exists, replace the tag in --ref with the exact candidate commit SHA and record that SHA as the tested subject. This candidate-only route must not appear in the user prompt and must not be described as a published Preview.

An unpinned development route remains available for repository maintainers:

codex plugin marketplace add iorLab/svif --ref main

--ref main selects a moving development ref. It is not a Preview release and its current repository SHA is only comparison evidence unless the client exposes the exact accepted revision.

For workspace-managed testing, use the repository URL as Source, leave Path empty because the marketplace manifest is at the repository root, and prefer a fixed commit when exact provenance matters. Workspace repository policy values are not workspace execution authority.

Repository Preview success remains distinct from public-directory publication and from personal ChatGPT installation evidence. The public personal-user target remains the universal Plugins Directory after the separate OpenAI submission and review flow.

Installation and invocation evidence

For any real supported surface, record the exact surface, observed installation state, revision/version provenance when exposed, invocation path, Agnir activation/discovery, verification, any trusted authority use, independent observation for external effects, and resulting durable checkpoint.

For the primary consumer target, the first decisive exercise is:

public universal Plugins Directory -> personal ChatGPT Web -> install Svif -> invoke on a real Agnir Project -> verify -> checkpoint -> fresh-context resume

Only that observed exercise establishes the personal ChatGPT Web installation baseline. Repository CI, marketplace import, public review approval, and directory publication are related but distinct evidence layers.

Future MCP/App increment

Add MCP/App packaging only when Svif needs concrete server-backed capabilities that the Skill-only Plugin cannot provide and the surface consequences have been tested. The increment must reuse the existing ChatGPT Execution Surface and Orchestrator.begin() / Orchestrator.complete() lifecycle, preserve protected authority outside model-controlled payloads, and avoid creating a second kernel or continuity store.

Do not add MCP merely as a prerequisite for public publication: current OpenAI public submission explicitly accepts Skills-only Plugins.