diff --git a/README.md b/README.md index 143562f..591c79f 100644 --- a/README.md +++ b/README.md @@ -65,7 +65,11 @@ The Playground publishes canonical, Open Graph, Twitter Card, and `WebApplicatio The required CI baseline compares the pin against GitHub's latest stable release and resolved tag commit, executes documentation commands using both the pinned source and the attested published Linux archive, and verifies that an unsupported flag fails the documentation smoke. Offline documentation builds check locale version consistency without contacting GitHub. The read-only `Release freshness` workflow checks daily and on manual dispatch, so a CLI-only release cannot remain silently stale until someone edits this repository. A failed run requires a synchronization PR and a verified Web deployment; this workflow does not auto-merge or auto-publish. GitHub scheduled runs may be delayed, and GitHub Actions notification preferences govern failure notifications. -## Playground scope +## Coding agent skill + +Install the focused diagram skill with `npx skills add stack-sh/web --skill stack-diagrams` in the target project. It provides instructions, not a CLI binary. See the [coding agent guide](https://stack-diagram.com/docs/guide/coding-agents) for a copyable prompt, local validation loop, installation boundaries, and limitations. `skills/stack-diagrams/SKILL.md` is the maintained source; its CLI examples run alongside documentation examples against the published CLI in CI. + +## Playground features The initial playground includes: diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index b6b57a9..a6e56f4 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -69,6 +69,7 @@ type Labels = { guide: string introduction: string gettingStarted: string + codingAgents: string examples: string playground: string providerIcons: string @@ -133,6 +134,7 @@ const en: Labels = { guide: "Guide", introduction: "What is Stack?", gettingStarted: "Getting started", + codingAgents: "Coding agents", examples: "Examples", playground: "Using the Playground", providerIcons: "Provider icons", @@ -162,6 +164,7 @@ const ja: Labels = { guide: "ガイド", introduction: "Stackとは", gettingStarted: "はじめる", + codingAgents: "Coding agentで使う", examples: "Example gallery", playground: "Playgroundの使い方", providerIcons: "Provider icon", @@ -191,6 +194,7 @@ const zh: Labels = { guide: "指南", introduction: "什么是 Stack？", gettingStarted: "快速开始", + codingAgents: "Coding agent", examples: "示例库", playground: "使用 Playground", providerIcons: "云服务商图标", @@ -220,6 +224,7 @@ const ko: Labels = { guide: "가이드", introduction: "Stack이란?", gettingStarted: "시작하기", + codingAgents: "Coding agent", examples: "예제 갤러리", playground: "Playground 사용법", providerIcons: "클라우드 제공자 아이콘", diff --git a/docs/guide/coding-agents.md b/docs/guide/coding-agents.md new file mode 100644 index 0000000..de8d82d --- /dev/null +++ b/docs/guide/coding-agents.md @@ -0,0 +1,42 @@ +# Coding agents + +Use Stack with a coding agent to keep architecture diagrams as reviewable source. The agent can read the language reference and run the CLI locally; a remote MCP server is not required. + +## Install the skill + +Install only the diagram skill with `npx skills add stack-sh/web --skill stack-diagrams`. This installs into the current project; add `-g` only when you want a user-wide installation. Review the downloaded instructions before use. This installs instructions, not the Stack CLI. For a reproducible installation, clone the repository, check out a reviewed commit, then run `npx skills add /absolute/path/to/web --skill stack-diagrams`. The installer does not accept a raw commit SHA as a remote branch. + +[SKILL.md](https://github.com/stack-sh/web/blob/main/skills/stack-diagrams/SKILL.md) + +## Without installation + +Copy this instruction into your agent and add the architecture requirements. The same prompt works without a skill-aware client, provided it can read HTTPS pages and execute local commands. + +```text +Use Stack to create or edit the architecture described below. Read https://stack-diagram.com/docs/llms.txt and the relevant syntax/examples. Preserve all requested components and relationships. Save editable architecture.stack. Check the installed CLI version/help, then check, format, and render architecture.svg locally. Read warnings as well as exit status, fix errors without removing requirements, and inspect the SVG if a viewer is available. Do not invent syntax or provider icon IDs. Report artifact paths, CLI version, and any validation gaps. Ask before installation or third-party terms acceptance when not already authorized. +``` + +## Validate locally + +Install the CLI through [Getting started](./getting-started). Check its version and help rather than relying on unreleased GitHub main features. CLI 0.4.0 does not support check/render `--json`. + +```sh +$ stack --version +$ stack help +$ stack check architecture.stack +$ stack fmt architecture.stack +$ stack check architecture.stack +$ stack render architecture.stack -o architecture.svg +``` + +## Icons and limitations + +Do not guess provider icon IDs or accept third-party terms automatically. Use semantic kinds when a pack is unavailable, and state that vendor artwork was not rendered. If the CLI or a viewer is unavailable, report the corresponding validation gap. Successful compilation does not prove readable layout. + +## Reference and updates + +- [Examples](../examples/index) +- [Syntax](../language/syntax) +- [Diagnostics](../reference/diagnostics-and-limits) +- [Provider icons](./provider-icons) +- [Markdown index](https://stack-diagram.com/docs/llms.txt) diff --git a/docs/ja/guide/coding-agents.md b/docs/ja/guide/coding-agents.md new file mode 100644 index 0000000..f827217 --- /dev/null +++ b/docs/ja/guide/coding-agents.md @@ -0,0 +1,42 @@ +# Coding agentで使う + +Coding agentでStackを読み書きすると、構成図をレビュー可能なsourceとして管理できます。言語referenceを読み、CLIをlocal実行するため、remote MCP serverは不要です。 + +## Skillの導入 + +`npx skills add stack-sh/web --skill stack-diagrams`で図作成skillだけをcurrent projectへ導入します。User全体へ導入したい場合だけ`-g`を付け、取得したinstructionを確認してください。CLI本体は別途必要です。再現可能な導入にはrepositoryをcloneして確認済みcommitをcheckoutし、`npx skills add /absolute/path/to/web --skill stack-diagrams`で導入します。Installerはcommit SHAをremote branchとして直接指定する方法には対応していません。 + +[SKILL.md](https://github.com/stack-sh/web/blob/main/skills/stack-diagrams/SKILL.md) + +## 導入せずに使う + +次のinstructionをagentへ渡し、作りたい構成を追記してください。HTTPSの参照とlocal command実行ができれば、skillに未対応のclientでも使えます。 + +```text +Use Stack to create or edit the architecture described below. Read https://stack-diagram.com/docs/llms.txt and the relevant syntax/examples. Preserve all requested components and relationships. Save editable architecture.stack. Check the installed CLI version/help, then check, format, and render architecture.svg locally. Read warnings as well as exit status, fix errors without removing requirements, and inspect the SVG if a viewer is available. Do not invent syntax or provider icon IDs. Report artifact paths, CLI version, and any validation gaps. Ask before installation or third-party terms acceptance when not already authorized. +``` + +## Localで検証 + +[はじめる](./getting-started)からCLIを導入し、未公開mainの機能ではなく実binaryのversionとhelpを確認します。CLI 0.4.0のcheck/renderは`--json`に未対応です。 + +```sh +$ stack --version +$ stack help +$ stack check architecture.stack +$ stack fmt architecture.stack +$ stack check architecture.stack +$ stack render architecture.stack -o architecture.svg +``` + +## Iconと制限 + +Provider icon IDを推測せず、第三者termsを自動承認しないでください。Packがなければsemantic kindを使い、vendor artworkが表示されていないと明示します。CLIやviewerが使えなければ未検証の範囲を報告します。Compile成功だけでは見やすい図とは限りません。 + +## 参照と更新 + +- [Examples](../examples/index) +- [Syntax](../language/syntax) +- [Diagnostics](../reference/diagnostics-and-limits) +- [Provider icons](./provider-icons) +- [Markdown index](https://stack-diagram.com/docs/llms.txt) diff --git a/docs/ko/guide/coding-agents.md b/docs/ko/guide/coding-agents.md new file mode 100644 index 0000000..59f5449 --- /dev/null +++ b/docs/ko/guide/coding-agents.md @@ -0,0 +1,42 @@ +# Coding agent 사용 + +Coding agent로 Stack을 읽고 쓰면 아키텍처 다이어그램을 검토 가능한 소스로 관리할 수 있습니다. 언어 레퍼런스를 읽고 CLI를 로컬에서 실행하므로 원격 MCP 서버가 필요하지 않습니다. + +## Skill 설치 + +`npx skills add stack-sh/web --skill stack-diagrams`로 현재 프로젝트에 다이어그램 skill만 설치합니다. 사용자 전체에 설치하려는 경우에만 `-g`를 추가하고 다운로드한 지침을 검토하세요. CLI는 별도로 설치해야 합니다. 재현 가능한 설치에는 저장소를 clone하고 검토한 commit을 checkout한 다음 `npx skills add /absolute/path/to/web --skill stack-diagrams`를 실행하세요. 설치 프로그램은 commit SHA를 원격 브랜치로 직접 지정하는 방식을 지원하지 않습니다. + +[SKILL.md](https://github.com/stack-sh/web/blob/main/skills/stack-diagrams/SKILL.md) + +## 설치 없이 사용 + +다음 지침을 agent에게 전달하고 아키텍처 요구 사항을 추가하세요. HTTPS 문서를 읽고 로컬 명령을 실행할 수 있다면 skill 미지원 클라이언트에서도 사용할 수 있습니다. + +```text +Use Stack to create or edit the architecture described below. Read https://stack-diagram.com/docs/llms.txt and the relevant syntax/examples. Preserve all requested components and relationships. Save editable architecture.stack. Check the installed CLI version/help, then check, format, and render architecture.svg locally. Read warnings as well as exit status, fix errors without removing requirements, and inspect the SVG if a viewer is available. Do not invent syntax or provider icon IDs. Report artifact paths, CLI version, and any validation gaps. Ask before installation or third-party terms acceptance when not already authorized. +``` + +## 로컬 검증 + +[시작하기](./getting-started)에서 CLI를 설치하고 미출시 main 기능 대신 실제 바이너리의 버전과 도움말을 확인하세요. CLI 0.4.0의 check/render는 `--json`을 지원하지 않습니다. + +```sh +$ stack --version +$ stack help +$ stack check architecture.stack +$ stack fmt architecture.stack +$ stack check architecture.stack +$ stack render architecture.stack -o architecture.svg +``` + +## 아이콘과 제한 + +제공자 아이콘 ID를 추측하거나 제삼자 약관을 자동으로 수락하지 마세요. 팩이 없으면 의미에 맞는 kind를 사용하고 브랜드 아이콘이 표시되지 않았음을 알리세요. CLI 또는 뷰어를 사용할 수 없으면 미검증 범위를 보고하세요. 컴파일 성공이 읽기 쉬운 배치를 보장하지는 않습니다. + +## 레퍼런스와 업데이트 + +- [Examples](../examples/index) +- [Syntax](../language/syntax) +- [Diagnostics](../reference/diagnostics-and-limits) +- [Provider icons](./provider-icons) +- [Markdown index](https://stack-diagram.com/docs/llms.txt) diff --git a/docs/public/llms.txt b/docs/public/llms.txt index 28661b2..b359979 100644 --- a/docs/public/llms.txt +++ b/docs/public/llms.txt @@ -6,6 +6,8 @@ These Markdown pages are the public user-facing reference. Examples marked as `s ## Guide +- [Coding agents](https://stack-diagram.com/docs/guide/coding-agents.md): Install the Stack diagram skill, copy a prompt, and validate source with the published local CLI. + - [What is Stack?](https://stack-diagram.com/docs/guide/what-is-stack.md): Goals, conceptual model, processing pipeline, and deliberate non-goals. - [Getting started](https://stack-diagram.com/docs/guide/getting-started.md): Package installation, first diagram, engine operations, and browser Playground workflow. - [Example gallery](https://stack-diagram.com/docs/examples/index.md): Curated starter-to-production corpus with canonical source, generated thumbnails, provider requirements, and expected structure. diff --git a/docs/zh/guide/coding-agents.md b/docs/zh/guide/coding-agents.md new file mode 100644 index 0000000..e661784 --- /dev/null +++ b/docs/zh/guide/coding-agents.md @@ -0,0 +1,42 @@ +# 使用 coding agent + +使用 coding agent 读写 Stack，可将架构图作为可审查的源文件管理。agent 阅读语言参考并在本地执行 CLI，不需要远程 MCP 服务器。 + +## 安装 skill + +使用 `npx skills add stack-sh/web --skill stack-diagrams` 仅将图表 skill 安装到当前项目。仅在需要用户级安装时添加 `-g`，并检查下载的指令。CLI 需要单独安装。需要可复现安装时，先 clone 仓库并 checkout 已审核的 commit，再运行 `npx skills add /absolute/path/to/web --skill stack-diagrams`。安装器不能将 commit SHA 直接作为远程分支安装。 + +[SKILL.md](https://github.com/stack-sh/web/blob/main/skills/stack-diagrams/SKILL.md) + +## 不安装也能使用 + +将以下指令复制给 agent，并补充架构需求。只要客户端可以读取 HTTPS 页面和运行本地命令，即使不支持 skill 也能使用。 + +```text +Use Stack to create or edit the architecture described below. Read https://stack-diagram.com/docs/llms.txt and the relevant syntax/examples. Preserve all requested components and relationships. Save editable architecture.stack. Check the installed CLI version/help, then check, format, and render architecture.svg locally. Read warnings as well as exit status, fix errors without removing requirements, and inspect the SVG if a viewer is available. Do not invent syntax or provider icon IDs. Report artifact paths, CLI version, and any validation gaps. Ask before installation or third-party terms acceptance when not already authorized. +``` + +## 本地验证 + +通过[快速开始](./getting-started)安装 CLI。检查实际二进制的版本和帮助，不要依赖尚未发布的 main 功能。CLI 0.4.0 的 check/render 不支持 `--json`。 + +```sh +$ stack --version +$ stack help +$ stack check architecture.stack +$ stack fmt architecture.stack +$ stack check architecture.stack +$ stack render architecture.stack -o architecture.svg +``` + +## 图标与限制 + +不要猜测提供商图标 ID 或自动接受第三方条款。缺少图标包时使用语义 kind，并说明没有呈现品牌图标。如果无法使用 CLI 或查看器，请报告未验证范围。编译成功不代表布局清晰。 + +## 参考与更新 + +- [Examples](../examples/index) +- [Syntax](../language/syntax) +- [Diagnostics](../reference/diagnostics-and-limits) +- [Provider icons](./provider-icons) +- [Markdown index](https://stack-diagram.com/docs/llms.txt) diff --git a/public/llms.txt b/public/llms.txt index eabea89..532d79e 100644 --- a/public/llms.txt +++ b/public/llms.txt @@ -6,6 +6,8 @@ Stack source describes components, boundaries, relationships, themes, and layout ## Documentation +- [Coding agents](https://stack-diagram.com/docs/guide/coding-agents.md): Install the Stack diagram skill or copy a minimal instruction; generate, validate, and render with the published local CLI. + - [Stack documentation](https://stack-diagram.com/docs/llms.txt): Curated guides, complete language reference, diagnostics, limits, versioning, and safety information. - [Complete English documentation](https://stack-diagram.com/llms-full.txt): All English documentation in one Markdown document for agents that prefer a single context. - [Getting started](https://stack-diagram.com/docs/guide/getting-started.md): Install the browser package, write a first `.stack` document, and use the Playground. diff --git a/scripts/docs-validation.config.mjs b/scripts/docs-validation.config.mjs index 902713c..c1eaa9d 100644 --- a/scripts/docs-validation.config.mjs +++ b/scripts/docs-validation.config.mjs @@ -7,6 +7,7 @@ export const documentationContract = { items: [ { label: "introduction", page: "guide/what-is-stack.md" }, { label: "gettingStarted", page: "guide/getting-started.md" }, + { label: "codingAgents", page: "guide/coding-agents.md" }, { label: "examples", page: "examples/index.md" }, { label: "playground", page: "guide/playground.md" }, { label: "providerIcons", page: "guide/provider-icons.md" }, diff --git a/scripts/validate-docs-cli.mjs b/scripts/validate-docs-cli.mjs index 4e31b60..17527b4 100644 --- a/scripts/validate-docs-cli.mjs +++ b/scripts/validate-docs-cli.mjs @@ -23,6 +23,13 @@ const { documents, cliExamples } = await validateDocumentationContract({ exceptions: documentationContract.exceptions, }) +const skill = await readFile("skills/stack-diagrams/SKILL.md", "utf8") +assert.match(skill, /^---\nname: stack-diagrams\ndescription: .+\nlicense: Apache-2.0\n---/) +const skillCommands = [...skill.matchAll(/```sh\n([\s\S]*?)```/g)].flatMap((match) => + match[1].trim().split("\n"), +) +assert.ok(skillCommands.length > 0, "Skill must include executable CLI examples") + const temporaryDirectory = await mkdtemp(path.join(os.tmpdir(), "stack-docs-cli-")) try { const environment = { @@ -69,7 +76,7 @@ try { const usedExceptions = new Set() let executedExamples = 0 - for (const command of [...new Set(cliExamples)]) { + for (const command of [...new Set([...cliExamples, ...skillCommands])]) { const exception = [...configuredExceptions.keys()].find((prefix) => command.startsWith(prefix)) if (exception) { usedExceptions.add(exception) diff --git a/skills/stack-diagrams/SKILL.md b/skills/stack-diagrams/SKILL.md new file mode 100644 index 0000000..5727171 --- /dev/null +++ b/skills/stack-diagrams/SKILL.md @@ -0,0 +1,46 @@ +--- +name: stack-diagrams +description: Create or edit Stack (.stack) software architecture diagrams, validate them with the Stack CLI, and render SVG. Use for Stack diagrams or when a user chooses Stack for architecture documentation; not for infrastructure provisioning or unrelated programming stacks. +license: Apache-2.0 +--- + +# Stack diagrams + +Deliver editable `.stack` source and, when rendering is available, an SVG. Preserve the requested architecture and existing unrelated content. Stack describes architecture; it does not provision resources or execute application code. + +## Start with the available tools + +Run `stack --version` and `stack help` before selecting commands. Use the installed binary's help, not unreleased repository instructions. The published CLI 0.4.0 supports `check`, `fmt`, and `render`; it does not support their `--json` flags. A newer version may support additional options: verify them using `stack help `. + +If the CLI is missing, consult the [installation guide](https://stack-diagram.com/docs/guide/getting-started.md) and [release distribution contract](https://github.com/stack-sh/cli/blob/v0.4.0/docs/distribution.md). Install only when the user's authorization allows it. Otherwise provide source with an explicit validation gap; do not report it as checked. No remote source upload is required. + +## Read only the relevant reference + +Start with [syntax](https://stack-diagram.com/docs/language/syntax.md), [nodes and groups](https://stack-diagram.com/docs/language/nodes-and-groups.md), and [edges and layout](https://stack-diagram.com/docs/language/edges-and-layout.md) when the grammar is unfamiliar. Find complete examples in the [gallery](https://stack-diagram.com/docs/examples/index.md). The [documentation index](https://stack-diagram.com/docs/llms.txt) links the remaining references. If the client cannot fetch one resource, try its Markdown page or report the missing information rather than inventing syntax. + +Non-obvious constraints: + +- One `stack 1.0` declaration and one named `diagram`; node/group IDs are globally unique. +- Declare edges at diagram scope. Endpoints are node IDs, not labels or groups. +- Model technologies using labels and `detail`; choose semantic `kind` values from the reference. Do not invent properties such as coordinates, colors, or ports. +- Prefer automatic layout or `direction` initially. `order` controls relative cross-axis ordering, not execution sequence; add `rank` or `order` only when the user needs that constraint. References must be direct children of that layout scope. +- Do not guess vendor icon IDs. Consult [provider icons](https://stack-diagram.com/docs/guide/provider-icons.md), query `stack icons list`, and verify the required pack is installed. Import downloads and terms acceptance need appropriate user authorization. If no pack is available, use the semantic kind fallback and explain that branded artwork is absent. + +## Generate, validate, and render + +For a new diagram, start with the smallest complete source that preserves the requested components and relationships. For an edit, inspect the existing source first and retain unrelated nodes, edges, labels, and comments. + +Using the user's actual filenames: + +```sh +stack check architecture.stack +stack fmt architecture.stack +stack check architecture.stack +stack render architecture.stack -o architecture.svg +``` + +`fmt` changes the source in place; avoid unrelated formatting when it would obscure a narrowly requested edit. Rendering to a file may replace it, so honor existing artifact ownership. + +Read both the exit status and diagnostics. An exit code of zero can still carry warnings. Fix unknown references or invalid syntax from the diagnostic ranges; never remove requested architecture merely to make validation pass. Investigate layout warnings without treating an optional visual hint as a required semantic relationship. Missing-icon warnings mean the image rendered with a fallback, not that provider artwork was found. Bound repeated repair attempts and report a remaining blocker rather than silently weakening the task. + +After rendering, inspect the SVG visually when a suitable viewer is available. Compiler success does not prove readable layout. Confirm the requested nodes, boundaries, relationships, and labels remain present. Report the source/SVG paths, CLI version, validation result, and any unresolved warnings or unverified visual behavior.