@passioncode-ai/passioncode 0.1.4

package/payload/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: adapting-projects-to-fabric
+description: Use when adapting an existing agent, MCP server, A2A peer, HTTP service, or terminal CLI to the Fabric Agent Contract—choosing MCP/A2A/local-runner, scaffolding a provider bundle, or checking Fabric compatibility; also for «подключить проект к Fabric» or «сделать агента совместимым с Fabric». NOT for building the Fabric host/orchestrator, configuring an MCP client, or a brand-new agent — that is creating-fabric-agents.
+license: MIT
+compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned private fabric-agent-contract checkout. Works without those tools in an explicitly degraded structural-check mode.
+metadata:
+  author: passioncode-ai
+  version: "0.4.2"
+  contract-version: "0.1.0"
+  contract-commit: "20a818e648a4c09a60df0126d11626922e8b9094"
+---
+
+# Adapting projects to Fabric
+
+Turn an existing stable interface into a proposed Fabric provider bundle, then prove
+only the compatibility gates for which receipts exist. The Fabric Agent Contract is
+normative; this skill is an authoring workflow pinned to one immutable revision.
+
+## Boundary
+
+Use this skill to adapt or assess a provider project. Do not use it to:
+
+- design the Fabric host, registry, scheduler, admission service, or project binding runtime;
+- add an MCP server to Claude Code, Codex, or an agent gateway;
+- design a new agent from scratch — that is the sibling skill creating-fabric-agents;
+- claim admission merely because generated files or a valid manifest exist.
+
+If the project has only a browser interface and no stable API, MCP/A2A surface, or CLI,
+stop with that missing prerequisite. Browser automation is not a base Fabric profile.
+
+## Required inputs
+
+Establish these values from the request or target repository:
+
+- project root;
+- the one capability being adapted;
+- stable provider and capability URIs;
+- who owns the task lifecycle;
+- the interface Fabric can actually reach;
+- expected inputs, outputs, effects, data classes, and safe probe behaviour;
+- a public or private immutable base URI for published schemas and fixtures.
+
+Do not ask for all fields before inspecting. Discover safe facts first and ask only
+for decisions that remain material. Never request or copy secret values into the bundle.
+
+## Workflow
+
+### 1. Inspect without execution
+
+Resolve this skill's directory and run:
+
+```bash
+python3 <skill-dir>/scripts/adapt_project.py inspect <project-root> --json
+```
+
+The inspector samples repository files but does not execute the project. Verify its
+evidence manually. Existing runtime documentation and code outrank filename heuristics.
+
+If the inspector returns `undetermined`, answer its lifecycle question before creating
+files. A repository can expose multiple surfaces; choose a profile per capability, not
+per vendor. Load [profile selection](references/profile-selection.md) whenever choosing
+or reviewing a profile.
+
+### 2. Pin the normative contract
+
+Use exactly:
+
+- contract version `0.1.0`;
+- repository `https://github.com/passioncode-ai/fabric-agent-contract`;
+- commit `20a818e648a4c09a60df0126d11626922e8b9094`.
+
+Read the pinned contract's guide
+`docs/guides/connecting-compatible-agents.md`, the selected profile specification, and
+the referenced JSON Schemas before implementing protocol details. If the private checkout
+is unavailable, continue only through local structure and mark exact schema validation
+`NOT_RUN`; do not reconstruct missing normative rules from memory.
+
+### 3. Scaffold the provider bundle
+
+Load [provider bundle](references/provider-bundle.md) before creating or mapping files.
+Then run one explicit profile command:
+
+```bash
+python3 <skill-dir>/scripts/adapt_project.py scaffold <project-root> \
+  --profile mcp \
+  --provider-id https://agents.example/providers/example \
+  --provider-name "Example provider" \
+  --capability-id https://agents.example/capabilities/example \
+  --capability-name example.run \
+  --schema-base https://agents.example/fabric
+```
+
+Valid profiles are `mcp`, `a2a`, and `local-runner`. The helper creates only the locked
+target paths. It refuses any collision. Do not use `--force` unless the user explicitly
+authorizes replacement after the exact conflicting files and diff are shown.
+
+The generated zero hash, `.invalid` endpoints, `replace-me` values, generic schemas, and
+assertions are deliberate blockers. Replace them with implementation-backed facts. A
+template that still contains one is not ready for admission.
+
+### 4. Implement the adapter seam
+
+Preserve the chosen ownership boundary:
+
+- A2A maps the provider's remote task, progress, artifact, cancellation, and terminal
+  states; Fabric does not take over its internal loop.
+- MCP exposes bounded tools/resources/prompts while Fabric owns planning and retries.
+- Local runner maps typed input, executable identity, result location, cancellation,
+  heartbeat, and partial results without relying on ambient accounts.
+
+Keep model selection and provider-internal reasoning outside the Fabric contract. Expose
+typed outcomes, evidence, artifacts, and protocol-visible state—not chain-of-thought.
+Treat all provider output as untrusted until schemas and semantic assertions pass.
+
+### 5. Make probes safe and meaningful
+
+For each capability, create at least one bounded fixture that:
+
+- can run repeatedly;
+- has an explicit timeout;
+- cannot publish, charge, message real recipients, or mutate production;
+- validates the declared output shape;
+- tests a semantic property a fake or wrong implementation would fail;
+- preserves a typed partial/stopped result on timeout or cancellation.
+
+A transport success is not semantic success. Assertions such as “returns JSON” are too
+weak; assert the capability's intended meaning and evidence obligations.
+
+### 6. Run independent checks
+
+First run local structure:
+
+```bash
+python3 <skill-dir>/scripts/adapt_project.py check <project-root> --json
+```
+
+When the exact contract checkout and dependencies are available, run:
+
+```bash
+python3 <skill-dir>/scripts/adapt_project.py check <project-root> \
+  --contract /path/to/fabric-agent-contract --json
+```
+
+Load [verification](references/verification.md) before interpreting or publishing the
+result. Fix every local error. Fix every placeholder warning or record why the bundle is
+still a draft. Do not convert `NOT_RUN` or `NOT_VERIFIED` to `PASS` without the named
+runtime receipt.
+
+### 7. Update the conformance report
+
+Update `fabric/FABRIC-CONFORMANCE.md` with dated receipts for:
+
+1. declaration shape;
+2. exact protocol negotiation;
+3. bounded semantic probes;
+4. project-binding readiness.
+
+Include commands and exit codes, immutable endpoint or artifact identities, and explicit
+unverified surfaces. If live Fabric admission/runtime does not yet exist, the last gates
+remain `NOT VERIFIED`; the completed deliverable is an adaptation-ready provider bundle,
+not a connected provider.
+
+## Completion format
+
+Report:
+
+- selected capability and profile, with lifecycle-owner evidence;
+- created or changed files;
+- contract version and commit;
+- gate table with `PASS`, `FAIL`, `NOT_RUN`, or `NOT_VERIFIED`;
+- remaining placeholders and blockers;
+- the exact next command or runtime action.
+
+Never summarize the outcome as “Fabric-compatible” unless all required admission gates
+passed against a real provider and the project binding is valid.

package/payload/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/references/profile-selection.md

@@ -0,0 +1,71 @@
+# Profile selection
+
+Load this reference when choosing or reviewing a profile for one capability.
+
+## Decision
+
+```text
+Does a remote peer accept an outcome and own task progress, artifacts,
+cancellation, and terminal state?
+  yes -> A2A 1.0
+  no  -> Does Fabric call a bounded remote or stdio capability?
+          yes -> MCP 2026-07-28
+          no  -> Does Fabric start an installed terminal process?
+                  yes -> fabric-local-runner/0.1
+                  no  -> unsupported until a stable surface exists
+```
+
+The protocol is selected per capability. A provider may expose several capabilities
+through different profiles, but one capability cannot change profile during a pinned run.
+
+## A2A
+
+Use when the remote system owns an opaque autonomous task lifecycle. Require:
+
+- HTTPS Agent Card and stable skill IDs;
+- A2A `1.0` binding and authentication declaration;
+- mapping for submitted, working, input-required, completed, failed, and cancelled states;
+- artifact and evidence mapping;
+- cancellation and safe semantic probes.
+
+An ordinary job API may be wrapped as A2A only when the adapter faithfully owns these
+task semantics. A long HTTP request alone is not proof of autonomy.
+
+## MCP
+
+Use when Fabric owns planning, ordering, retries, and task completion while invoking
+bounded provider features. Require:
+
+- MCP `2026-07-28` over streamable HTTP or stdio;
+- exact required feature names (`tool:`, `resource:`, or `prompt:`);
+- typed inputs and outputs;
+- idempotency and effect declarations;
+- bounded feature-level probes.
+
+An MCP server is a capability provider, not automatically an autonomous peer.
+
+## Local runner
+
+Use when Fabric launches an installed process such as a coding CLI. Require:
+
+- profile `fabric-local-runner/0.1`;
+- stable `executableRef`, never a secret-bearing shell string;
+- argument array and typed input mode;
+- immutable result URI convention;
+- signal or declared cancellation behaviour;
+- heartbeat and partial-result behaviour;
+- project-scoped account selection outside the manifest.
+
+The user may choose the project's default terminal and override it per agent. Model choice
+stays inside the selected agent/provider; the Fabric profile remains model-agnostic.
+
+## Reject or defer
+
+Return `undetermined` or blocked when:
+
+- more than one surface exists and the requested capability is unclear;
+- task lifecycle ownership is not observable;
+- the only integration surface is a browser UI;
+- the provider cannot supply typed input/output boundaries;
+- safe non-publishing probes cannot be defined.
+

package/payload/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/references/provider-bundle.md

@@ -0,0 +1,62 @@
+# Provider bundle
+
+Load this reference before scaffolding files or implementing the adapter mapping.
+
+## Files
+
+| Path | Responsibility |
+|---|---|
+| `fabric-agent.json` | versioned provider identity, capabilities, effects, profile, and probes |
+| `fabric-contract.lock.json` | normative repository, contract version, immutable commit, selected profile |
+| `fabric/schemas/capability-input.schema.json` | provider-specific input boundary |
+| `fabric/schemas/capability-output.schema.json` | provider-specific output boundary |
+| `fabric/fixtures/admission-input.json` | bounded repeatable probe input |
+| `fabric/probes/assertions.md` | semantic and safety properties checked by admission |
+| `fabric/FABRIC-CONFORMANCE.md` | receipts and explicit unverified gates |
+
+The layout packages an implementation; it does not replace the normative contract.
+
+## Manifest mapping
+
+For every capability, establish:
+
+- a stable provider URI, monotonic revision, immutable content hash, author, and identity method;
+- a stable capability URI and semantic name independent of implementation or model;
+- absolute, immutable input/output schema URIs;
+- the real side-effect class and idempotency behaviour;
+- every accepted data class;
+- exactly one profile and exact revision;
+- safe input fixture, output schema, timeout, effect ceiling, and semantic assertions.
+
+Do not include tokens, passwords, cookies, account IDs selected from an ambient shell, raw
+environment dumps, or chain-of-thought. A future project binding supplies allowlisted
+secret references, account pools, grants, data policy, coordination, and checker policy.
+
+## Implementation seam
+
+| Existing project | Adapter responsibility |
+|---|---|
+| Native MCP | map stable features directly and preserve MCP errors/cancellation |
+| Native A2A | declare the Agent Card/skills and normalize artifacts/evidence |
+| Terminal CLI | create typed input/result adapters and stable executable identity |
+| Bounded HTTP API | wrap operations with MCP while Fabric owns the loop |
+| Autonomous job API | map job lifecycle and artifacts to A2A tasks |
+| Browser-only app | first add a supported stable API or CLI |
+
+Completed and stopped invocations ultimately map to the Fabric result envelope: atomic
+`done` claims, resolvable `proof`, pinned `scope`, `notVerified`, and immutable artifacts.
+Provider-specific output schemas do not remove that normalization obligation.
+
+## Normative paths at the pinned commit
+
+Read these from `fabric-agent-contract` rather than copying them here:
+
+- `schemas/manifest.schema.json`
+- `schemas/result.schema.json`
+- `schemas/binding.schema.json`
+- `docs/specification/profiles.md`
+- `docs/specification/results-and-evidence.md`
+- `docs/specification/registry.md`
+- `docs/specification/versioning.md`
+- `fixtures/positive/manifest-{mcp,a2a,local}.json`
+

package/payload/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/references/verification.md

@@ -0,0 +1,55 @@
+# Verification and verdicts
+
+Load this reference before interpreting checks or writing a conformance claim.
+
+## Independent gates
+
+| Gate | PASS requires | Does not prove |
+|---|---|---|
+| Local structure | expected files parse, lock matches, revision fields are exact, no forbidden secret-like fields | normative JSON Schema validity |
+| Declaration shape | pinned contract validator accepts the real manifest | endpoint identity, reachability, or behaviour |
+| Protocol negotiation | live provider accepts the exact MCP/A2A/local-runner revision and identity checks | semantic correctness |
+| Semantic probes | bounded fixtures produce typed outputs and satisfy meaning/evidence assertions | authorization for a project |
+| Binding readiness | admitted capability can be pinned with project context, pool, grants, policies, and checker | that a binding has been activated |
+
+Use only `PASS`, `FAIL`, `NOT_RUN`, and `NOT_VERIFIED`:
+
+- `NOT_RUN`: the check exists but its required tool, checkout, endpoint, or credential was unavailable.
+- `NOT_VERIFIED`: no implemented verifier/runtime currently exists for the claim.
+- Never relabel either as a warning-level pass.
+
+## Receipts
+
+A receipt names what ran and what identity was tested:
+
+- command and exit code;
+- contract commit and schema ID;
+- provider revision/content hash;
+- endpoint or executable identity;
+- fixture and immutable result/artifact URI;
+- assertion results and unverified surfaces;
+- admission and binding revisions when they exist.
+
+Transport logs without semantic assertions are insufficient. A prose statement without a
+resolvable receipt remains unverified.
+
+## Degraded operation
+
+If the pinned contract checkout or its dependencies are absent:
+
+1. run local structure only;
+2. retain declaration shape as `NOT_RUN`;
+3. name the exact pinned checkout and command needed;
+4. continue implementation only as a draft.
+
+If the Fabric host/admission runtime is absent, protocol, semantics, and binding remain
+`NOT_VERIFIED`. Deliver the provider bundle and adapter tests, but do not claim it is
+connected or admitted.
+
+## Replacement and rollback
+
+Any manifest change produces a new provider revision and content hash. It must receive a
+new admission decision and a new project-binding revision. Existing runs stay pinned.
+Rollback creates another binding revision based on known-good immutable inputs; it never
+rewrites history.
+