diff --git a/.github/workflows/skill-preview.yml b/.github/workflows/skill-preview.yml new file mode 100644 index 0000000..60c71a4 --- /dev/null +++ b/.github/workflows/skill-preview.yml @@ -0,0 +1,13 @@ +name: Skill Review +on: + pull_request: + paths: ['**/SKILL.md'] +jobs: + review: + runs-on: ubuntu-latest + permissions: + pull-requests: write + contents: read + steps: + - uses: actions/checkout@v4 + - uses: tesslio/skill-review@22e928dd837202b2b1d1397e0114c92e0fae5ead # main \ No newline at end of file diff --git a/skills/enterprise-readiness-protocol/SKILL.md b/skills/enterprise-readiness-protocol/SKILL.md index 4622a67..f819227 100644 --- a/skills/enterprise-readiness-protocol/SKILL.md +++ b/skills/enterprise-readiness-protocol/SKILL.md @@ -1,10 +1,6 @@ --- name: enterprise-readiness-protocol -description: > - The Enterprise Readiness Protocol specification — the open standard - format for declaring what vendors need from enterprise environments. - Includes canonical dependency types for deterministic matching. - Loaded automatically by interf-draft and interf-preview. +description: "Defines the interf.yaml schema for enterprise readiness contracts — validation rules, field specifications, and canonical dependency types. Provides spec.md for schema reference and examples.md for realistic contract templates. Loaded automatically by interf-draft and interf-preview when drafting or previewing enterprise rollout contracts." user-invocable: false --- @@ -14,18 +10,29 @@ An open standard for declaring what vendors need from enterprise environments be ## Contract Format -See [spec.md](./spec.md) for the `interf.yaml` schema: -- `requirements` — what you need, with `what` + `ready` acceptance criteria -- `optional` — nice-to-have dependencies -- `canonical` — optional reference to a canonical dependency type +Every contract is an `interf.yaml` file with `what` + `ready` pairs: -## Examples +```yaml +name: acme-crm-automation +version: 0.1.0 +description: Automates CRM data entry -See [examples.md](./examples.md) for realistic contracts across different rollout types. +requirements: + - what: Read/write access to your CRM (contacts and opportunities) + ready: We can create a contact and read an opportunity via API from staging + canonical: integration.crm.api + +optional: + - what: Webhook endpoint for real-time CRM updates + ready: We receive a test webhook payload within 5 seconds of a CRM update + canonical: integration.webhook.outbound +``` + +See [spec.md](./spec.md) for the full schema and validation rules. See [examples.md](./examples.md) for realistic contracts across different rollout types. ## How It Works -1. **Declare** — Vendor declares `interf.yaml` with every enterprise dependency. +1. **Draft** — Vendor creates `interf.yaml` listing every enterprise dependency with `what` + `ready` criteria. Run `npx interf validate` to check schema and canonical type IDs. 2. **Deliver** — Contract is published to the Interf registry or sent directly to enterprise. 3. **Resolve** — Enterprise works through each requirement, audited against the `ready` criteria. -4. **Verify** — All requirements resolved. Rollout can proceed. +4. **Verify** — All requirements resolved and acceptance criteria met. Rollout can proceed. diff --git a/skills/interf-draft/SKILL.md b/skills/interf-draft/SKILL.md index bb0c992..e331de2 100644 --- a/skills/interf-draft/SKILL.md +++ b/skills/interf-draft/SKILL.md @@ -1,14 +1,11 @@ --- name: interf-draft -description: > - Draft an interf.yaml readiness contract by scanning the codebase for - enterprise dependencies, or define them manually. Use when you need to - specify what you need from enterprise before rollout. +description: "Draft an interf.yaml readiness contract by scanning the codebase for enterprise dependencies — API endpoints, auth providers, infrastructure requirements, and stakeholder needs — or define them manually. Use when creating rollout prerequisites, pre-launch checklists, or specifying what a vendor needs from enterprise before deployment." --- -# Declare Readiness Contract +# Draft Readiness Contract -Extract or define an `interf.yaml` readiness contract declaring what you need from enterprise environments. +Extract or define an `interf.yaml` readiness contract declaring what the project needs from enterprise environments. ## Before You Start @@ -16,18 +13,14 @@ Extract or define an `interf.yaml` readiness contract declaring what you need fr ## Step 1: Analyze the Project -- What does this project do and who are the enterprise users? -- What external systems does it connect to? -- What data access is needed? -- What authentication/authorization is required? -- Who needs to be involved on the enterprise side? -- What reviews or approvals are typical? +Scan the codebase for enterprise dependencies: -Look at: -- Configuration files (environment variables, API endpoints, auth config) -- Integration code (API clients, database connections, webhook handlers) -- Documentation (architecture docs, setup guides, runbooks) -- Deployment config (infrastructure requirements, network rules) +- **Configuration files** — environment variables, API endpoints, auth config +- **Integration code** — API clients, database connections, webhook handlers +- **Deployment config** — infrastructure requirements, network rules, environment setup +- **Documentation** — architecture docs, setup guides referencing external systems + +Identify what external systems, data access, authentication, stakeholders, and approval processes the project depends on. ## Step 2: Map to Canonical Types @@ -74,7 +67,7 @@ optional: 5. **Include stakeholder dependencies.** If someone needs to be involved (data team, security team), that's a requirement too. 6. **Include process dependencies.** Security review, compliance review, training — these are the blockers FDEs hate discovering mid-flight. -## Step 4: Validate (Optional) +## Step 4: Validate After writing `interf.yaml`, validate it against the protocol schema and canonical types: @@ -87,4 +80,4 @@ This checks: - Canonical type IDs against the latest known types - Suggests corrections for shorthand or hallucinated IDs (e.g. `sso` → `auth.sso.saml`) -If the CLI is not installed, suggest the user run `npx interf validate` — it auto-installs and validates in one step. +If validation fails, fix the flagged issues and re-run until the contract passes. If the CLI is not installed, `npx interf validate` auto-installs and validates in one step. diff --git a/skills/interf-preview/SKILL.md b/skills/interf-preview/SKILL.md index 01f8e3b..7c91e60 100644 --- a/skills/interf-preview/SKILL.md +++ b/skills/interf-preview/SKILL.md @@ -1,9 +1,6 @@ --- name: interf-preview -description: > - Preview enterprise rollout against a company profile. Produces - resolution timelines, identifies stakeholders, and surfaces risks. - Use when you want to understand what rollout looks like at a specific enterprise. +description: "Preview enterprise rollout against a company profile — produces resolution timelines, identifies stakeholders, maps dependency chains, and surfaces risks. Use when generating a deployment plan, implementation preview, or go-to-market readiness assessment for a specific enterprise customer." --- # Preview Enterprise Rollout @@ -14,6 +11,7 @@ Generate a rollout preview for a specific enterprise based on an `interf.yaml` r 1. **Load the contract.** Read the project's `interf.yaml`. If none exists, run the `interf-draft` skill first. 2. **Load canonical types.** Read [canonical-dependencies/index.md](../protocol/canonical-dependencies/index.md) for dependency relationships, blockers, and sector patterns. +3. **Verify inputs.** Confirm the contract has at least one requirement with `what` + `ready` fields. If any `canonical` IDs are present, verify they resolve against the canonical-dependencies reference. ## Step 1: Build Enterprise Profile @@ -23,6 +21,8 @@ Research the target enterprise: - **Known systems** — Salesforce, SAP, Okta, etc. (from public info, job postings, tech stack databases) - **Regulatory environment** — HIPAA, PCI-DSS, SOX, GDPR, etc. +Verify the profile covers all four dimensions before proceeding — gaps here cascade into inaccurate timelines. + ## Step 2: Analyze Each Requirement For each requirement in the contract: @@ -36,6 +36,8 @@ For each requirement in the contract: - **Risks** — what could go wrong (from key risks / common gotchas) - **Complexity** — from the canonical type's complexity field +Flag any requirements where canonical types could not be resolved or where sector/system data is missing. + ## Step 3: Build Resolution Timeline 1. Order requirements by dependency chain (what blocks what) @@ -43,17 +45,23 @@ For each requirement in the contract: 3. Group parallel work streams 4. Flag high-risk items +Example dependency chain: `auth.sso.saml` → `integration.crm.api` → `data.historical-export` (SSO must be live before CRM API access, which must be live before historical data export can begin). + ## Step 4: Present the Preview For each requirement: -- Resolution approach and steps -- Stakeholders involved -- Estimated complexity (low / medium / high) -- Risks and mitigations -- What it's blocked by + +| Field | Description | +|-------|-------------| +| **Requirement** | The `what` from the contract | +| **Approach** | Resolution steps for this enterprise | +| **Stakeholders** | Who needs to be involved | +| **Complexity** | Low / Medium / High | +| **Risks** | What could go wrong and mitigations | +| **Blocked by** | Other requirements that must resolve first | Summary: -- **Critical path** with ordered dependencies -- **Parallel work streams** that can run concurrently -- **Top risks** across the rollout -- **Key stakeholders** and their involvement +- **Critical path** — ordered dependency chain with the longest sequential resolution time +- **Parallel work streams** — requirements that can be resolved concurrently +- **Top risks** — highest-impact risks across the rollout with mitigations +- **Key stakeholders** — all involved parties and their requirements