contract diagram

Diagram as contract for agreed-upon AI development

Security Scan

This skill runs a local Node server (not declared as a requirement) that will fetch arbitrary filesystem paths and offers a write endpoint — behavior that is plausible for a 'diagram viewer' but is broader than the manifest/instructions claim and presents clear host-file exposure risks.

Purpose & Capability

The skill's stated purpose is to render and manage 'contract' diagrams. The code and SKILL.md implement a local web viewer that reads markdown files and supports sign‑off (write). That functionality is coherent with the description. However the package does not declare that it requires Node.js (server.js) nor does the metadata warn that the server will read arbitrary filesystem paths — an omission that is disproportionate to the 'instruction-only' appearance in the registry metadata.

Instruction Scope

Runtime instructions explicitly tell the agent to start the bundled server and open localhost with an md parameter pointing at arbitrary file paths (examples show '../../../...'). The web UI (index.html + server.js) will fetch and serve arbitrary paths supplied via the URL, and the client will POST to /write to test write permission. The SKILL.md therefore directs the agent to read (and optionally write) local files beyond the skill directory — this expands the scope to full host file access and is a material risk if the user or agent supplies sensitive paths.

Install Mechanism

There is no install spec, but the bundle contains server.js and a shell launcher (serve.sh) that invoke node. The manifest declares no required binaries or dependencies; in practice Node.js must be present to run the skill. That mismatch (no declared runtime requirement but included Node server) is an incoherence and a usability/security risk.

Credentials

The skill requests no environment variables or credentials, which is consistent. However it exposes a /realpath endpoint and a file-read capability that can be used to enumerate or read host files. Although no secrets are requested explicitly, the ability to fetch arbitrary files from the host is functionally equivalent to requesting broad filesystem access and should be considered high-scope from a secrets perspective.

Persistence & Privilege

The skill launches a background HTTP server process (serve.sh -> node server.js) on port 8080. While always:false and autonomous invocation are not set to force inclusion, when invoked this creates a persistent local server that serves files and accepts write requests. That persistence increases blast radius (running process exposing endpoints) and should be considered when granting permission to start the skill.

Scan Findings in Context

[base64-block] unexpected: A 'base64-block' prompt-injection pattern was detected in SKILL.md. The file contents visible here don't show obvious base64 payloads, but the scanner flagged an injection pattern. This could be a false positive or a sign the skill author attempted to embed a payload; combined with the server that will fetch arbitrary paths, it is additional reason for caution.

What to consider before installing

This skill will start a local Node-based HTTP server (serve.sh / server.js) that renders a mermaid/markdown file from a path you supply and also exposes endpoints to check realpaths and to write files. Before running it: 1) Do not run on a sensitive host or with elevated privileges; prefer a disposable VM, container, or sandbox. 2) Verify you have Node.js and that the manifest is updated to declare that dependency (the registry metadata currently does not). 3) Inspect server.js carefully — the read/GET handling does not restrict reads to the engine directory, so a crafted ?md=/../../path request can return arbitrary files from the host. 4) If you need write behavior, consider patching server.js to strictly canonicalize and whitelist allowed paths and to require explicit user confirmation before POST /write performs any change. 5) Treat the base64-block scan finding as suspicious: ask the author for clarification or remove any hidden/encoded payloads. If you cannot audit or harden the server, do not run this skill on machines that contain secrets or sensitive data.

Legend	Description
	Not discussed yet
	Agreed by stakeholders
	Needs discussion/failed implementation (always has notes)
	Agreed and implemented
	Implemented but developer made decisions (in notes)
	(dashed border) To be performed outside system

---

SKILL contract diagram ℹ️

%%{init: {'theme':'base','themeVariables':{"primaryColor":"#4A90E2","primaryTextColor":"#fff","primaryBorderColor":"#2E5C8A","lineColor":"#666","secondaryColor":"#50E3C2","tertiaryColor":"#FFD700","edgeLabelBackground":"#666"},'flowchart':{"nodeSpacing":50,"rankSpacing":50,"padding":15,"curve":"basis"}}}%%
flowchart TD
    TRIGGER["Trigger + contract"]
    CHECK_CONTRACT{"Has contract?"}
    OPEN["Open contract"]
    CLARIFY["Clarify"]
    CHECK_DIAGRAM{"Has diagram?"}
    CREATE["New 1️⃣"]
    CLAIM["Claimed 1️⃣"]
    ERROR["Error 2️⃣"]
    
    DESIGN["Design phase"]
    SIGNOFF["Ready to approve"]
    DEVELOPMENT["Developing..."]
    BLOCKERS{"Has blockers?"}
    TESTS{"Pass checks? 3️⃣"}
    PUBLISH["Publish 3️⃣"]
    
    TRIGGER --> CHECK_CONTRACT
    CHECK_CONTRACT -->|Yes| OPEN
    CHECK_CONTRACT -->|Yes but<br/>not editable| ERROR
    CHECK_CONTRACT -->|No| CLARIFY
    CLARIFY --> TRIGGER
    
    OPEN --> CHECK_DIAGRAM
    CHECK_DIAGRAM -->|Yes, more<br/>than one| ERROR
    CHECK_DIAGRAM -->|Yes, one| CLAIM
    CHECK_DIAGRAM -->|No| CREATE
    
    CREATE --> DESIGN
    CLAIM --> DESIGN
    DESIGN --> SIGNOFF
    SIGNOFF -->|Approved| DEVELOPMENT
    DEVELOPMENT --> BLOCKERS
    BLOCKERS -->|Yes| DESIGN
    BLOCKERS -->|No| TESTS
    TESTS -->|Yes| PUBLISH
    TESTS -->|No| DESIGN
    
    classDef default fill:#e0e0e0,stroke:#666,color:#000
    classDef approved fill:#FFF9C4,stroke:#F9A825,color:#000
    classDef developed fill:#D5F5D5,stroke:#388E3C,color:#000
    classDef blocker fill:#FFCDD2,stroke:#D32F2F,color:#000
    classDef notes fill:#E3F2FD,stroke:#1976D2,color:#000
    classDef outside fill:#D5F5D5,stroke:#388E3C,stroke-dasharray:5 5,color:#000
    
    class CHECK_DIAGRAM,CREATE,CLAIM,ERROR,SIGNOFF,DESIGN,DEVELOPMENT,BLOCKERS,CHECK_CONTRACT,OPEN,CLARIFY,TRIGGER developed
    class PUBLISH,TESTS outside

1️⃣ Wrapper auto-injects title + phase badge + CSS on first load and watches for change of phase on badge.

2️⃣ More than one diagram confuses system. For now, only one per md in order to run.

3️⃣ Checks and publication depend on what and where final product goes, so it's user discretion.

---

Numbered Notes (1️⃣ 2️⃣ 3️⃣)

When to use:

Pre-execution (design phase):

• Questions that need discussion
• Trade-offs that need decisions
• Unclear requirements

During execution:

• Errors AI can't resolve alone
• Permission needed (destructive action, cost implications)
• Ambiguity in implementation

Format:

### 1️⃣ [Component Name] - [Issue Title]
**Question/Error:** ...
**Context:** ...
**Options:** A, B, C
**Needed:** Decision / Permission / Help

Notes without numbers = just explanations, turn yellow when approved.

---

Localhost Trigger

Trigger: "lets diagram [PATH]"

Assumes: File at PATH already has mermaid diagram.

Action:

1. Start localhost server (port 8080)
2. Open browser with diagram

Example:

User: "lets diagram epic-notes/webhook-contract.md"

AI executes:
  cd ~/Documents/skills/contract-diagram/engine
  ./serve.sh &
  open "http://localhost:8080/?md=../../epic-notes/webhook-contract.md"

Hot reload enabled by default (2s interval).

---