Business Blueprint

Use when turning presales requirements, meeting notes, or solution materials into editable business capability blueprints, swimlane flows, and application ar...

Security Scan

The skill is internally consistent with its stated purpose (local Python scripts that generate blueprint JSON and diagram exports), but there are a few documentation/instruction mismatches you should review before use.

Purpose & Capability

Name/description, CLI surface (plan/project/export/validate) and the included Python scripts align: the repo contains a blueprint generator, exporters (SVG, drawio, Excalidraw, Mermaid), templates and viewer assets needed for the stated functionality. However, documentation is inconsistent: SKILL.md and many scripts instruct direct execution of scripts (python scripts/business_blueprint/cli.py), while README files still show pip install -e . and other packaging instructions. PURE_SKILL_CLEANUP.md claims package/test files were removed but the manifest still includes many test files and package-like files. These are likely stale docs, not an active security problem, but they are a coherence issue to be aware of.

Instruction Scope

SKILL.md explicitly instructs the agent to read industry seed templates in the repo and to extract entities from user-provided source text, then write blueprint JSON and export artifacts into projects/workspace/. This is coherent for the skill's purpose. The CLI supports --from <file> which allows reading arbitrary user-supplied files (expected). There are no instructions to read unrelated system paths or environment variables. As usual, granting the agent access to user files/content to parse is required for its function — verify the agent is only given the specific source text/files you intend it to process.

Install Mechanism

No install spec is provided (instruction-only skill), which reduces install-time risk. The runtime model is local script execution (python scripts/...). That is proportional to the functionality. Note the README still documents pip install -e . and package installation; because no install spec exists in the registry, prefer following SKILL.md's direct-script usage. The presence of many code files means the agent will execute code from the skill repo, so inspect scripts before running in a sensitive environment.

Credentials

The skill declares no required environment variables, no credentials, and no required binaries. That matches the stated local, zero-external-dependency design. README mentions Python >= 3.12 (runtime requirement) which is reasonable. There are no obvious requests for unrelated secrets or credentials in SKILL.md or the manifest.

Persistence & Privilege

Flags show always:false (not force-included) and default agent-invocation behavior. The skill writes generated artifacts to projects/workspace/ (a relative path declared in SKILL.md) which is expected for export generation. There is no indication the skill modifies other skills or requests elevated platform privileges.

Assessment

This skill appears to do what it says: local Python scripts generate blueprint JSON and diagram exports. Before installing or running it, I recommend: 1) Inspect the repository files (especially scripts/business_blueprint/cli.py, export_svg.py and export_* files) to confirm there are no unexpected network calls or data exfiltration (look for imports/use of requests, urllib, socket, subprocess spawning with remote URLs). 2) Note the documentation mismatch: prefer SKILL.md (direct script usage) over README's pip install instructions; confirm you want to execute repository scripts rather than installing as a package. 3) Run the skill in an isolated/sandboxed environment (or container) so file writes go to a controlled location; the skill writes to projects/workspace/ by default. 4) Only supply the agent with source files/text you are comfortable sharing and do not feed secrets or credentials. 5) If you need higher assurance, grep the code for outbound network usage and run the tests / a dry-run on non-sensitive input first. If you want, I can scan the codefiles for network/OS calls and report any matches.

Business Blueprint Skill

Use the Python scripts in this repository as the execution surface.

Output Directory

All generated files (blueprint JSON, viewers, exports) go into projects/workspace/ — not the repository root.

python scripts/business_blueprint/cli.py --plan projects/workspace/solution.blueprint.json --from "..."
python scripts/business_blueprint/cli.py --project projects/workspace/solution.blueprint.json
python scripts/business_blueprint/cli.py --export projects/workspace/solution.blueprint.json

Industry Selection

Choose --industry from exactly one of: "common", "finance", "manufacturing", "retail". Select the closest match based on the user's domain and materials; do not invent other values.

Industry	Hints content
common	No hints — generic domains
finance	Risk control, credit, compliance, customer profile, etc.
manufacturing	Production planning, quality, warehouse, supply chain, etc.
retail	Store operations, membership, POS, order fulfillment, etc.

How to Generate a Blueprint

The AI agent is responsible for entity extraction. The Python tool handles JSON writing, visualization, and export.

Step 1: Read industry hints

Read the seed template at business_blueprint/templates/{industry}/seed.json and get the industryHints.checklist.

Step 2: Extract entities from source text

Using the user's source material AND the industry hints checklist, extract:

• capabilities: business capability areas (name, description)
• actors: roles/people involved (name)
• flowSteps: business process steps (name, actorId, capabilityIds, stepType)
• systems: IT systems that support capabilities
  • See references/entities-schema.md for all entity field definitions
  • See references/systems-schema.md for systems category/layer rules
  • See scripts/business_blueprint/templates/common/seed.json for field examples

Step 3: Write the blueprint JSON

Write the JSON file directly to the output path. Use this schema:

{
  "version": "1.0",
  "meta": {
    "title": "...",
    "industry": "retail",
    "revisionId": "rev-YYYYMMDD-NN",
    "parentRevisionId": null,
    "lastModifiedAt": "ISO8601",
    "lastModifiedBy": "ai"
  },
  "context": {
    "goals": [],
    "scope": [],
    "assumptions": [],
    "constraints": [],
    "sourceRefs": [{"type": "inline-text", "excerpt": "..."}],
    "clarifyRequests": [],
    "clarifications": []
  },
  "library": {
    "capabilities": [
      {"id": "cap-xxx", "name": "...", "level": 1, "description": "...", "ownerActorIds": [], "supportingSystemIds": []}
    ],
    "actors": [
      {"id": "actor-xxx", "name": "..."}
    ],
    "flowSteps": [
      {"id": "flow-xxx", "name": "...", "actorId": "actor-xxx", "capabilityIds": ["cap-xxx"], "systemIds": [], "stepType": "task", "inputRefs": [], "outputRefs": []}
    ],
    "systems": [
      {"id": "sys-xxx", "kind": "system", "name": "...", "aliases": [], "description": "...", "resolution": {"status": "canonical", "canonicalName": "..."}, "capabilityIds": ["cap-xxx"]}
    ]
  },
  "relations": [
    {"id": "rel-xxx", "type": "supports", "from": "sys-xxx", "to": "cap-xxx", "label": "支撑"}
  ],
  "views": [],
  "editor": {"fieldLocks": {}, "theme": "enterprise-default"},
  "artifacts": {}
}

Step 4: Generate visualizations

python scripts/business_blueprint/cli.py --export <blueprint.json>

This generates SVG + HTML viewer by default. Use --format drawio|excalidraw|mermaid for other formats.

Export View Selection Policy

Treat export view choice as a routing decision, not a styling preference.

• If a request matches a supported, standard export template, use that template.
• If there is no standard export template for the requested diagram, fall back to freeflow.
• Do not substitute swimlane, matrix, product tree, or other generic views just because they are available.
• When embedding a blueprint diagram into a report or ad hoc analysis, freeflow is the safe default unless the user explicitly asks for a supported standard template.

Step 5: Generate downstream projection

python scripts/business_blueprint/cli.py --project <blueprint.json>

This generates solution.projection.json, the canonical machine projection consumed by downstream report/slide workflows.

Workflow Decision Tree

User provides raw requirements / meeting notes?
  → AI agent reads hints, extracts entities, writes blueprint JSON
  → Optionally run --project for downstream machine handoff
  → Then run --export for visualization

User needs diagram files (SVG, draw.io, etc.)?
  → --export (default: SVG + HTML viewer)

User unsure about blueprint quality?
  → --validate

User wants downstream report / slide generation?
  → --project

Commands

Command	Description
--plan <path> --from <text>	Generate empty blueprint JSON from source text (AI should prefer writing JSON directly)
--project <path>	Generate canonical projection JSON for downstream skills
--export <path>	Export SVG + HTML viewer (default), or use --format for other formats
--validate <path>	Validate a blueprint and print JSON results

Execution: Run directly as scripts:

python scripts/business_blueprint/cli.py --plan ...
python scripts/business_blueprint/cli.py --export ...

Export Formats

Format	File	Use Case
svg (default)	solution.exports/solution.svg + HTML viewer	Quick preview, embedding
drawio	solution.exports/solution.drawio	Editable diagrams
excalidraw	solution.exports/solution.excalidraw	Whiteboard-style diagrams
mermaid	solution.exports/solution.mermaid.md	GitHub-native rendering

Collaboration Boundary

This skill produces semantic intermediate artifacts. Downstream skills consume them:

• report-creator consumes solution.projection.json → assembles reports
• slide-creator consumes solution.projection.json → assembles presentations
• Other skills may consume relations → generate PlantUML or other diagram syntax
• Downstream skills should never directly edit solution.blueprint.json
• solution.handoff.json is viewer-only metadata, not a downstream narrative input

Sandbox Execution

When running in an isolated Python sandbox (Jupyter, notebook, cloud REPL) that auto-installs dependencies:

1. The sandbox uses scripts directly. Run execution scripts from the repository root:

   import subprocess
   subprocess.run(["python", "scripts/business_blueprint/cli.py", "--export", "solution.blueprint.json"])
   

   • sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) — will raise NameError
   • subprocess.run(["business-blueprint", ...]) — sandbox runs Python cells, not shell
   • os.system() — same reason

Architecture Diagram Generation

When user requests an architecture diagram (keywords: "架构图", "architecture diagram", "--export", "diagram"):

1. Read references/architecture-design-system.md for the complete design system.
2. Read the appropriate template from references/architecture-templates/ based on the user's domain:
   • AWS/Serverless/Lambda → serverless.md
   • Microservices/Kubernetes/微服务 → microservices.md
   • Other → use serverless.md as a structural reference
3. Read the blueprint JSON to extract entities and flow steps.
4. Generate a self-contained HTML file with inline SVG following the design system rules.
5. Write the output file to the same directory as the blueprint JSON.

If the request does not match one of the supported standard templates above, stay on the default freeflow export path. Do not switch to another generic view type as a fallback. If a standard template would create a squeezed, clipped, or overcrowded diagram, stop using the fixed template geometry and fall back to freeflow or a wrapped multi-row layout.

Route eligibility matrix

Use an explicit route contract before rendering:

Route	Structural prerequisites	First fallback	Terminal behavior
freeflow	Any valid blueprint with at least one renderable node or relation	None	If integrity still fails, export exits non-zero with a structural diagnostics payload
architecture-template	Recognizable L→R architecture shape, categorized systems, limited per-layer density, and no route-breaking overflow risk	freeflow	Same as above
poster	Clear layer/group structure with bounded peer density per row or wrapped-row support	wrapped poster or freeflow	Same as above
swimlane	Actor-owned flow steps with meaningful lane grouping	freeflow	Same as above
hierarchy	Stable tree/group relationship with low ambiguity in parent-child grouping	freeflow	Same as above
evolution	Ordered chronological or staged progression data	freeflow	Same as above

Do not invent route heuristics ad hoc inside a renderer. Route eligibility must stay explicit and reviewable.

Generation Rules

• Use dark mode by default (#020617 bg + 40px grid). Only use light mode when the user explicitly asks for it.
• L→R data flow: Clients(左) → Frontend → Backend → Database(右)
• Map systems[].category to semantic colors from the design system
• Map systems[].properties.type == "aws" → AWS Region boundary box
• Map systems[].properties.type == "k8s" → Kubernetes Cluster boundary box
• Use flowSteps[].seqIndex for L→R ordering
• Component sizing: 0-1 cap = small(44px h), 2-4 = medium(80px h), 5+ = large(80px h)
• Layout must be content-driven. Never force every node in a layer into one fixed row if that creates toothpaste-style squeezing.
• When a layer has more than 3 peer nodes, or labels/features become tight, wrap into multiple rows or widen the canvas before shrinking the content.
• Render users/actors as actor labels, badges, or lane headers by default. Do not render them as ordinary system cards unless the user explicitly asks for that visual treatment.
• Legend must live in a bottom safe area and participate in canvas sizing. Never place the legend as a floating overlay in the top-right corner.
• Final SVG/HTML height must be derived from the bottom-most node, legend, summary cards, and footer plus padding. Do not use fixed-height wrappers or overflow: hidden that can clip the last row.
• Z-order: bg → grid → title → region → arrows → nodes → legend → cards → footer
• Component border: rx="8", stroke-width="2"
• Region border: rx="16", stroke-dasharray="8,4", opacity="0.4"
• Geometry-sensitive integrity checks must use the numeric thresholds from evals/export-integrity-thresholds.json, not prose heuristics.

Output

• Single HTML file: {blueprint_stem}.html alongside the blueprint JSON
• No external dependencies (except Google Fonts CDN for JetBrains Mono)
• Opens in any browser, printable to PDF

Error Handling

• If --validate returns errors: fix structural issues before proceeding to --export.
• If --validate returns only warnings: proceed but note the warnings in any handoff.
• If Python version < 3.12: the package will refuse to install. Use python3 -m business_blueprint.cli with system Python as fallback.
• If a specialized route fails integrity: fall back to its configured fallback route.
• If freeflow also fails integrity: export exits non-zero with a structural diagnostics payload instead of emitting a silently broken artifact.

Cross-Platform Scope

Phase 2 does not attempt full Windows terminal parity.

Known deferred cases:

• PowerShell pipe quirks beyond documented CLI contract tests
• console-default encoding issues outside explicit UTF-8 execution paths

Accepted workaround for encoding-sensitive runs:

Use scripts directly (pure Skill, no package structure)

subprocess.run(["python", "scripts/business_blueprint/cli.py", "--export", str(blueprint_path)])

• set PYTHONIOENCODING=utf-8 where needed