From ed8d6a2b4ac9766849015ab4df835356d56856c1 Mon Sep 17 00:00:00 2001 From: harumiWeb Date: Sat, 21 Mar 2026 20:02:33 +0900 Subject: [PATCH 1/5] Add ExStruct CLI skill for issue 115 --- .agents/skills/exstruct-cli/SKILL.md | 48 +++++++ .../skills/exstruct-cli/agents/openai.yaml | 4 + .../references/backend-constraints.md | 32 +++++ .../references/command-selection.md | 35 +++++ .../exstruct-cli/references/ops-guidance.md | 34 +++++ .../exstruct-cli/references/safe-editing.md | 40 ++++++ .../references/verify-workflows.md | 35 +++++ README.ja.md | 23 ++++ README.md | 25 ++++ ...09-single-cli-skill-for-agent-workflows.md | 91 +++++++++++++ dev-docs/adr/README.md | 1 + dev-docs/adr/decision-map.md | 6 + dev-docs/adr/index.yaml | 18 +++ dev-docs/specs/exstruct-cli-skill.md | 127 ++++++++++++++++++ tasks/feature_spec.md | 70 ++++++++++ tasks/lessons.md | 4 + tasks/todo.md | 28 ++++ 17 files changed, 621 insertions(+) create mode 100644 .agents/skills/exstruct-cli/SKILL.md create mode 100644 .agents/skills/exstruct-cli/agents/openai.yaml create mode 100644 .agents/skills/exstruct-cli/references/backend-constraints.md create mode 100644 .agents/skills/exstruct-cli/references/command-selection.md create mode 100644 .agents/skills/exstruct-cli/references/ops-guidance.md create mode 100644 .agents/skills/exstruct-cli/references/safe-editing.md create mode 100644 .agents/skills/exstruct-cli/references/verify-workflows.md create mode 100644 dev-docs/adr/ADR-0009-single-cli-skill-for-agent-workflows.md create mode 100644 dev-docs/specs/exstruct-cli-skill.md diff --git a/.agents/skills/exstruct-cli/SKILL.md b/.agents/skills/exstruct-cli/SKILL.md new file mode 100644 index 0000000..8e68113 --- /dev/null +++ b/.agents/skills/exstruct-cli/SKILL.md @@ -0,0 +1,48 @@ +--- +name: exstruct-cli +description: Use ExStruct CLI to validate, inspect, create, and edit Excel workbooks safely. Trigger when an agent needs `exstruct patch`, `exstruct make`, `exstruct validate`, `exstruct ops list`, or `exstruct ops describe`, especially for create-vs-edit decisions, dry-run workflows, backend constraints, or safe workbook-edit guidance. +--- + +# ExStruct CLI + +Use the existing editing CLI as the default local operational interface for +ExStruct workbook create/edit requests. + +## Select a command + +- Use `exstruct make` when the user wants a new workbook created and populated. +- Use `exstruct patch` when the user wants an existing workbook edited. +- Use `exstruct validate` when workbook readability is uncertain or before a + risky edit on an unfamiliar file. +- Use `exstruct ops list` when the required operation is still unclear. +- Use `exstruct ops describe ` when you know the likely op name but need + the exact schema or constraints. +- Hand the workflow off to MCP when the user needs host-owned path policy, + transport mapping, artifact mirroring, or other server-managed behavior. + +## Safety rules + +- Do not invent unsupported patch ops. +- Do not apply destructive edits immediately when the request is ambiguous. +- Prefer `--dry-run` before risky edits. +- Pin `--backend openpyxl` when the dry run and the real apply must use the + same engine. +- Explain backend-specific failures directly instead of hiding them behind a + generic retry. + +## Workflow + +1. Decide whether the request is create, edit, or actually an MCP-hosted task. +2. Identify the needed op or inspect the public op schema. +3. Validate the workbook when the file, backend, or request is uncertain. +4. Run `--dry-run` for risky edits and inspect `PatchResult`. +5. Apply the real edit only after the planned change is acceptable. +6. Verify the result with the lightest step that still matches the user's risk. + +## References + +- `references/command-selection.md` +- `references/safe-editing.md` +- `references/ops-guidance.md` +- `references/verify-workflows.md` +- `references/backend-constraints.md` diff --git a/.agents/skills/exstruct-cli/agents/openai.yaml b/.agents/skills/exstruct-cli/agents/openai.yaml new file mode 100644 index 0000000..7114e7d --- /dev/null +++ b/.agents/skills/exstruct-cli/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "ExStruct CLI" + short_description: "Guide safe ExStruct CLI edit workflows" + default_prompt: "Use $exstruct-cli to choose the right ExStruct editing CLI command, follow a safe validate/dry-run workflow, and explain any backend constraints for this workbook task." diff --git a/.agents/skills/exstruct-cli/references/backend-constraints.md b/.agents/skills/exstruct-cli/references/backend-constraints.md new file mode 100644 index 0000000..118d139 --- /dev/null +++ b/.agents/skills/exstruct-cli/references/backend-constraints.md @@ -0,0 +1,32 @@ +# Backend Constraints + +Use this file when the workflow depends on backend selection or runtime +capabilities. + +## Backend summary + +- `openpyxl` + - default choice for ordinary workbook edits + - supports `--dry-run`, `--return-inverse-ops`, and + `--preflight-formula-check` +- `com` + - required for COM-only editing behavior such as `create_chart` + - required for `.xls` creation/editing +- `auto` + - follows ExStruct's existing backend-selection policy + - can use openpyxl for a dry run and COM for the real apply + +## Constraints to call out + +- `create_chart` is COM-only. +- `.xls` workflows require COM and are not valid with `backend=openpyxl`. +- Requests that need host-owned path restrictions, transport mapping, or + artifact mirroring belong to MCP, not the local CLI Skill. + +## Failure behavior + +- State clearly when the requested backend or capability is unsupported. +- Do not pretend that `auto` guarantees the same engine across dry run and + apply. +- Redirect to MCP only for host-policy concerns, not as a generic substitute + for unsupported CLI behavior. diff --git a/.agents/skills/exstruct-cli/references/command-selection.md b/.agents/skills/exstruct-cli/references/command-selection.md new file mode 100644 index 0000000..f5b3097 --- /dev/null +++ b/.agents/skills/exstruct-cli/references/command-selection.md @@ -0,0 +1,35 @@ +# Command Selection + +Use this file when the user intent is clear enough to route to one CLI command +but the exact command is still undecided. + +## Primary routing + +- New workbook output requested: use `exstruct make`. +- Existing workbook path provided and the request changes it: use + `exstruct patch`. +- Readability or file-health check requested: use `exstruct validate`. +- Unknown capability or op name: use `exstruct ops list` first, then + `exstruct ops describe `. +- Host-owned path restrictions, transport, approval-aware execution, or + artifact mirroring requested: use MCP guidance instead of this Skill. + +## Request patterns + +- "Create a workbook with these starter sheets and values." + - `make` +- "Edit this workbook and set/update/merge/style cells." + - `patch` +- "I do not know which op supports this change." + - `ops list` or `ops describe` +- "Check whether this workbook is readable before we touch it." + - `validate` +- "Do this through the MCP server / Claude Desktop / host-managed policy." + - MCP docs, not the local CLI Skill + +## Escalate instead of guessing + +- Clarify the request before applying edits when the sheet, range, output path, + or intended effect is underspecified. +- If the user requests behavior outside the published op schema, say so and + offer the nearest supported workflow or a manual alternative. diff --git a/.agents/skills/exstruct-cli/references/ops-guidance.md b/.agents/skills/exstruct-cli/references/ops-guidance.md new file mode 100644 index 0000000..f0edd00 --- /dev/null +++ b/.agents/skills/exstruct-cli/references/ops-guidance.md @@ -0,0 +1,34 @@ +# Ops Guidance + +Use this file when the user knows the desired workbook outcome but the exact +patch op is unclear. + +## How to inspect ops + +- Run `exstruct ops list` when you need the supported op names and one-line + descriptions. +- Run `exstruct ops describe ` when you need exact fields, aliases, + backend constraints, or examples. + +## Common patterns + +- Single cell value/formula updates: + - inspect `set_value`, `set_formula`, and the conditional variants +- New worksheet creation: + - inspect `add_sheet` +- Rectangular data loads: + - inspect `set_range_values` +- Styling and layout: + - inspect `set_style`, `set_alignment`, `set_fill_color`, `set_bold`, + `auto_fit_columns`, `set_dimensions` +- Table or chart workflows: + - inspect `apply_table_style` and `create_chart` + +## Rules + +- Never invent an op name that `ops list` does not expose. +- Never guess required fields when `ops describe` can answer the question. +- Treat `create_chart` and `.xls` workflows as backend-sensitive and confirm the + backend before apply. +- If the user asks for behavior outside the op schema, say it is unsupported + and offer the closest supported path. diff --git a/.agents/skills/exstruct-cli/references/safe-editing.md b/.agents/skills/exstruct-cli/references/safe-editing.md new file mode 100644 index 0000000..c7e35df --- /dev/null +++ b/.agents/skills/exstruct-cli/references/safe-editing.md @@ -0,0 +1,40 @@ +# Safe Editing + +Use this file for risky edits, unfamiliar workbooks, or any request where a +wrong apply would be expensive. + +## Standard flow + +1. Validate the input workbook when readability is uncertain. +2. Build or inspect the patch-op JSON. +3. Run `exstruct patch --dry-run` for risky edits. +4. Inspect `PatchResult`, warnings, `patch_diff`, and `engine`. +5. Re-run without `--dry-run` only after the plan is acceptable. +6. Perform lightweight verification or deeper verification based on risk. + +## Ambiguity rules + +- Ask for clarification before apply when sheet names, target cells/ranges, + output naming, or overwrite policy are unclear. +- If the user only states a goal, inspect the op schema before inventing a + payload shape. + +## Risk checks + +- Treat destructive or broad edits as risky: + - overwrite/rename conflict decisions + - merge / unmerge operations + - range-wide formula fills + - style changes across large regions + - chart creation or COM-only workflows +- Prefer `--backend openpyxl` when you want the dry run and real apply to use + the same engine. +- Explain that `--backend auto` may use openpyxl for the dry run but COM for + the real apply on COM-capable hosts. + +## Failure behavior + +- Surface schema or validation failures directly. +- Do not silently retry with a different conceptual operation. +- If the request depends on unsupported runtime features, explain the + constraint and route to the correct backend or MCP workflow. diff --git a/.agents/skills/exstruct-cli/references/verify-workflows.md b/.agents/skills/exstruct-cli/references/verify-workflows.md new file mode 100644 index 0000000..3a323a8 --- /dev/null +++ b/.agents/skills/exstruct-cli/references/verify-workflows.md @@ -0,0 +1,35 @@ +# Verify Workflows + +Use this file after `patch` or `make`, or after a `--dry-run` when the result +must be inspected before apply. + +## Always check + +- CLI exit code +- `PatchResult.error` +- `PatchResult.warnings` +- `PatchResult.engine` +- `PatchResult.patch_diff` +- `PatchResult.out_path` + +## After `--dry-run` + +- Confirm that `patch_diff` matches the intended change. +- Confirm that warnings and formula issues are acceptable. +- If the user needs same-engine confidence, ensure the command pinned + `--backend openpyxl`. + +## After real apply + +- Re-run `exstruct validate` when the workbook was unfamiliar or the change was + operationally sensitive. +- Re-run extraction or another downstream read step when the workbook feeds a + larger pipeline and the user needs output-level confirmation. +- Prefer lightweight verification for small, low-risk edits and deeper + verification for wide-range, formula, chart, or backend-sensitive changes. + +## When lightweight verification is enough + +- The change is narrow and the `patch_diff` is easy to inspect. +- No backend-sensitive features were used. +- The user did not request stronger confirmation or downstream artifacts. diff --git a/README.ja.md b/README.ja.md index 9ac4633..f6293a0 100644 --- a/README.ja.md +++ b/README.ja.md @@ -121,6 +121,29 @@ exstruct validate --input book.xlsx --pretty 4. `--backend auto` を使う場合は `PatchResult.engine` を確認する。Windows/Excel 環境では実適用時に COM へ切り替わることがある。 5. 問題がなければ `--dry-run` なしで再実行する。 +## ExStruct CLI Skill + +ExStruct には、editing CLI を安全に使うための repo 管理 Skill も 1 つ含めています。 + +repo 上の正本: + +- `.agents/skills/exstruct-cli/` + +次の 1 コマンドでインストールできます。 + +```bash +npx skills add harumiWeb/exstruct/.agents/skills --skill exstruct-cli +``` + +このコマンドは、このリポジトリで公開される Skill ディレクトリから +`exstruct-cli` を直接追加する想定です。まだ未公開ブランチで作業している場合や、 +`npx skills add` を使えない実行環境では、従来どおり `SKILL.md` ベースの Skill を +検出するローカルディレクトリへ同じフォルダを手動配置してください。 + +この Skill は、`patch` / `make` / `validate` / `ops list` / +`ops describe` の使い分けや、安全な +`validate -> dry-run -> apply -> verify` フローが必要なときに使います。 + ## MCPサーバー (標準入出力) MCP は同じ editing core を包む integration / compatibility layer です。 diff --git a/README.md b/README.md index 885605a..9534bd0 100644 --- a/README.md +++ b/README.md @@ -133,6 +133,31 @@ Recommended edit flow: 4. If you keep `--backend auto`, inspect `PatchResult.engine`; on Windows/Excel hosts the real apply may switch to COM. 5. Re-run without `--dry-run` only after the result is acceptable. +## ExStruct CLI Skill + +ExStruct also ships one repo-owned Skill for agents that should follow the +editing CLI safely instead of rediscovering the workflow each time. + +Canonical repo source: + +- `.agents/skills/exstruct-cli/` + +You can install it with the following single command: + +```bash +npx skills add harumiWeb/exstruct/.agents/skills --skill exstruct-cli +``` + +That command should install `exstruct-cli` directly from this repository's +published Skill directory. If you are working from an unpublished branch or a +runtime that does not support `npx skills add`, fall back to copying the same +folder into the equivalent local skill directory that discovers `SKILL.md` +based skills. + +Use this Skill when the agent needs help choosing between `patch`, `make`, +`validate`, `ops list`, and `ops describe`, or when it should follow the safe +`validate -> dry-run -> apply -> verify` workflow. + ## MCP Server (stdio) MCP is the integration / compatibility layer around the same editing core. Use diff --git a/dev-docs/adr/ADR-0009-single-cli-skill-for-agent-workflows.md b/dev-docs/adr/ADR-0009-single-cli-skill-for-agent-workflows.md new file mode 100644 index 0000000..a94feeb --- /dev/null +++ b/dev-docs/adr/ADR-0009-single-cli-skill-for-agent-workflows.md @@ -0,0 +1,91 @@ +# ADR-0009: Single CLI Skill for Agent Workflows + +## Status + +`proposed` + +## Background + +ExStruct already exposes workbook editing through a stable local CLI: +`exstruct patch`, `exstruct make`, `exstruct ops`, and `exstruct validate`. +Those commands are intentionally positioned as the canonical local operational / +agent interface, while MCP remains the host-managed integration layer. + +That still leaves a recurring operational problem for AI agents: commands alone +do not tell an agent when to use `patch` versus `make`, when to inspect op +schemas, when to run `validate` or `--dry-run`, how to respond to unsupported +ops, or when the request actually belongs to MCP because host-owned safety +controls are required. + +The repository also needs one durable answer to two packaging questions that +would otherwise be re-decided repeatedly: + +- whether ExStruct should ship one Skill or multiple narrower Skills for CLI + editing +- whether the repository source of truth should live in the existing + `.agents/skills/` tree or add a second in-repo mirror such as + `.claude/skills/` + +## Decision + +- ExStruct adopts one installable Skill, `exstruct-cli`, for local AI-agent + workflows around the existing editing CLI. +- The canonical repository source of truth for that Skill is + `.agents/skills/exstruct-cli/`. +- The Skill consists of a lean `SKILL.md`, `agents/openai.yaml`, and focused + reference documents under `references/`. +- `SKILL.md` carries only trigger-oriented rules, safety rules, the standard + workflow, and direct navigation to the detailed references. +- Detailed operational knowledge such as command-selection guidance, risky-edit + workflow, backend constraints, and verification guidance lives in + `references/`. +- The Skill documents the CLI-versus-MCP boundary instead of collapsing both + into one agent workflow: + - local CLI Skill for local operational editing + - MCP docs for host-owned path policy, transport, and artifact behavior +- This issue does not add `.claude/skills/` mirrors, sync automation, or + Skill-local helper scripts/assets. + +## Consequences + +- ExStruct users and AI agents get one clear installation target for local CLI + editing guidance instead of choosing among overlapping Skills. +- The repository gains a durable, reviewable place for agent workflow policy + without changing the runtime CLI or MCP contracts. +- `SKILL.md` remains compact, which reduces trigger-time context cost and keeps + detailed material available on demand through `references/`. +- The local CLI guidance and MCP host-policy guidance stay separated, which + avoids teaching agents to bypass host-owned safety responsibilities. +- The chosen repo-only source-of-truth model keeps the repository simple, but it + leaves packaging or mirroring into other agent-specific directories as a + later concern. +- The initial implementation relies on lightweight validation and manual + scenario review rather than a dedicated automated eval harness, so deeper + agent-behavior testing remains future work if the Skill grows more complex. + +## Rationale + +- Tests: + - `tests/cli/test_edit_cli.py` + - `tests/cli/test_cli_lazy_imports.py` + - Skill-specific automated tests do not exist yet; the initial verification + path is `quick_validate.py` plus manual scenario review. +- Code: + - `src/exstruct/cli/main.py` + - `src/exstruct/cli/edit.py` + - `.agents/skills/exstruct-cli/SKILL.md` +- Related specs: + - `dev-docs/specs/editing-cli.md` + - `dev-docs/specs/exstruct-cli-skill.md` + - `docs/cli.md` + - `docs/mcp.md` + - `README.md` + - `README.ja.md` + +## Supersedes + +- None + +## Superseded by + +- None diff --git a/dev-docs/adr/README.md b/dev-docs/adr/README.md index 77a7ac4..4916d40 100644 --- a/dev-docs/adr/README.md +++ b/dev-docs/adr/README.md @@ -43,3 +43,4 @@ ADRs record what was decided, under which constraints, and which trade-offs were | `ADR-0006` | Public Edit API and Host-Owned Safety Boundary | `accepted` | `editing` | | `ADR-0007` | Editing CLI as Public Operational Interface | `accepted` | `editing` | | `ADR-0008` | Extraction CLI Runtime Capability Validation | `accepted` | `cli` | +| `ADR-0009` | Single CLI Skill for Agent Workflows | `proposed` | `agents` | diff --git a/dev-docs/adr/decision-map.md b/dev-docs/adr/decision-map.md index 2620cc7..8f4f1db 100644 --- a/dev-docs/adr/decision-map.md +++ b/dev-docs/adr/decision-map.md @@ -51,6 +51,11 @@ This document is a human-readable map for navigating ADRs by domain. - `ADR-0006` Public Edit API and Host-Owned Safety Boundary (`accepted`) - `ADR-0007` Editing CLI as Public Operational Interface (`accepted`) +- `ADR-0009` Single CLI Skill for Agent Workflows (`proposed`) + +## agents + +- `ADR-0009` Single CLI Skill for Agent Workflows (`proposed`) ## api @@ -60,6 +65,7 @@ This document is a human-readable map for navigating ADRs by domain. - `ADR-0007` Editing CLI as Public Operational Interface (`accepted`) - `ADR-0008` Extraction CLI Runtime Capability Validation (`accepted`) +- `ADR-0009` Single CLI Skill for Agent Workflows (`proposed`) ## Supersession Relationships diff --git a/dev-docs/adr/index.yaml b/dev-docs/adr/index.yaml index e2fcd6b..26f7d34 100644 --- a/dev-docs/adr/index.yaml +++ b/dev-docs/adr/index.yaml @@ -118,3 +118,21 @@ adrs: - README.md - README.ja.md - dev-docs/specs/excel-extraction.md + - id: ADR-0009 + title: Single CLI Skill for Agent Workflows + status: proposed + path: dev-docs/adr/ADR-0009-single-cli-skill-for-agent-workflows.md + primary_domain: agents + domains: + - agents + - cli + - editing + supersedes: [] + superseded_by: [] + related_specs: + - dev-docs/specs/editing-cli.md + - dev-docs/specs/exstruct-cli-skill.md + - docs/cli.md + - docs/mcp.md + - README.md + - README.ja.md diff --git a/dev-docs/specs/exstruct-cli-skill.md b/dev-docs/specs/exstruct-cli-skill.md new file mode 100644 index 0000000..4c355a3 --- /dev/null +++ b/dev-docs/specs/exstruct-cli-skill.md @@ -0,0 +1,127 @@ +# ExStruct CLI Skill Specification + +This document defines the internal contract for the installable `exstruct-cli` +Skill that teaches AI agents how to use the existing ExStruct editing CLI. + +## Purpose + +- Package safe operational knowledge for local CLI-based workbook editing. +- Reuse the existing public editing CLI contract instead of creating a new + runtime interface. +- Keep MCP host-policy concerns outside the Skill except where handoff guidance + is needed. + +## Non-goals + +- No change to CLI, Python API, or MCP runtime behavior. +- No `.claude/skills/` mirror or sync automation in the repository. +- No requirement to add Skill-local `scripts/` or `assets/` in the initial + implementation. + +## Canonical repo layout + +- Canonical source directory: `.agents/skills/exstruct-cli/` +- Required files: + - `SKILL.md` + - `agents/openai.yaml` + - `references/command-selection.md` + - `references/safe-editing.md` + - `references/ops-guidance.md` + - `references/verify-workflows.md` + - `references/backend-constraints.md` + +## Trigger and positioning contract + +- The Skill name is `exstruct-cli`. +- The frontmatter `description` must make the Skill trigger for: + - Excel workbook create/edit requests through ExStruct CLI + - `patch` versus `make` selection + - `validate` / `dry-run` / `ops describe` guidance + - safe CLI workflows for AI agents +- The Skill must position interfaces consistently with the public docs: + - use the editing CLI for local operational / agent workflows + - use MCP when host-owned path policy, transport, or artifact behavior is + required + - use `openpyxl` / `xlwings` for ordinary imperative Python editing + +## `SKILL.md` contract + +- Keep `SKILL.md` concise and workflow-oriented. +- Include only: + - YAML frontmatter with `name` and `description` + - command-selection rules + - safety rules + - standard workflow steps + - minimal examples + - direct links to each `references/` file +- Do not place large op catalogs, backend deep-dives, or long recipe + collections in `SKILL.md`. + +## `references/` contract + +### `references/command-selection.md` + +- Map user intents to `exstruct patch`, `exstruct make`, `exstruct validate`, + `exstruct ops list`, and `exstruct ops describe`. +- Define when the request should be redirected to MCP guidance instead of the + local CLI Skill. + +### `references/safe-editing.md` + +- Define the standard flow: + `validate -> dry-run -> inspect -> apply -> verify` +- Explain ambiguous-request handling and destructive-edit safeguards. +- Explain why `backend=openpyxl` is the safe default for same-engine dry-run + comparisons. + +### `references/ops-guidance.md` + +- Explain how to inspect supported ops before editing. +- State that unsupported ops must not be invented. +- Describe how to respond when the requested capability is missing or unclear. + +### `references/verify-workflows.md` + +- Define what to inspect in `PatchResult`. +- Define when re-validation or re-extraction is required. +- Define when lightweight verification is acceptable. + +### `references/backend-constraints.md` + +- Summarize `openpyxl`, `com`, and `auto` behavior relevant to agent guidance. +- Cover `.xls` and `create_chart` constraints. +- State explicit failure behavior for unsupported requests. + +## `agents/openai.yaml` contract + +- Must be present for repo consistency with other checked-in Skills. +- Must contain: + - `interface.display_name` + - `interface.short_description` + - `interface.default_prompt` +- Generate or refresh it with the external `skill-creator` helper script rather + than hand-maintaining inconsistent values. + +## Public docs obligations + +- `README.md` and `README.ja.md` must both: + - describe the Skill as one installable entry point + - explain the preferred one-command install path via + `npx skills add harumiWeb/exstruct/.agents/skills --skill exstruct-cli` + - explain the manual fallback for unpublished branches or runtimes that do + not support `npx skills add` + - describe when to use the Skill versus MCP documentation + - provide at least one minimal example prompt + +## Verification obligations + +- Validate the Skill folder with: + - `generate_openai_yaml.py` + - `quick_validate.py` +- Run `uv run task precommit-run`. +- Manually review representative scenarios for: + - create versus edit routing + - unknown-op handling + - risky-edit safety flow + - backend-constraint guidance + - CLI-versus-MCP boundary guidance diff --git a/tasks/feature_spec.md b/tasks/feature_spec.md index 39a7426..bd89550 100644 --- a/tasks/feature_spec.md +++ b/tasks/feature_spec.md @@ -98,3 +98,73 @@ - `not-needed` - rationale: this was release preparation and task-log retention cleanup. The shipped policy decisions already live in `ADR-0008`, the extraction docs/specs, and the architecture note. + +## 2026-03-21 issue #115 ExStruct CLI Skill + +### Goal + +- Add one installable Skill that teaches AI agents how to use the existing ExStruct editing CLI safely and consistently. +- Keep the current CLI, Python API, and MCP runtime contracts unchanged while packaging operational knowledge into repo-owned skill assets and durable documentation. +- Record the long-lived policy choices behind the Skill structure, CLI/MCP boundary, and distribution model in permanent documents before implementation logs are compressed. + +### Public contract summary + +- No changes to `exstruct patch`, `exstruct make`, `exstruct ops`, `exstruct validate`, `exstruct.edit`, or MCP tool payloads. +- Public docs gain one new documented interface layer: a single installable Skill named `exstruct-cli` for agent-side CLI workflows. +- `README.md` and `README.ja.md` must describe: + - where the Skill source lives in the repository + - how to install/copy it into an agent runtime + - when to use the Skill versus MCP guidance + - minimal usage examples / prompts + +### Internal Skill contract + +- Canonical repo source: `.agents/skills/exstruct-cli/` +- Required files: + - `SKILL.md` + - `agents/openai.yaml` + - `references/command-selection.md` + - `references/safe-editing.md` + - `references/ops-guidance.md` + - `references/verify-workflows.md` + - `references/backend-constraints.md` +- `SKILL.md` must stay lean and contain only trigger-oriented frontmatter, command selection rules, safety rules, workflow steps, and direct links to `references/`. +- `references/` must hold the detailed operational knowledge and avoid duplicating long catalogs inside `SKILL.md`. +- `scripts/` and `assets/` are out of scope for the initial implementation unless a concrete deterministic need appears during writing or validation. + +### Permanent destinations + +- `.agents/skills/exstruct-cli/` + - Canonical source for the installable Skill assets. +- `README.md` and `README.ja.md` + - Public installation and usage guidance for the Skill. +- `dev-docs/specs/` + - `dev-docs/specs/exstruct-cli-skill.md` is the canonical internal spec for the ExStruct CLI Skill contract and required reference structure. +- `dev-docs/adr/` + - `ADR-0009-single-cli-skill-for-agent-workflows.md` records the policy-level decisions: single Skill, repo-owned source of truth, and CLI-versus-MCP documentation boundary. +- `tasks/feature_spec.md` and `tasks/todo.md` + - Keep the working record only until the durable information above is written. + +### Constraints + +- Use the existing repository convention for skills (`.agents/skills/` + `agents/openai.yaml`); do not add `.claude/skills/` mirrors or sync automation in this issue. +- Keep the Skill focused on local CLI workflows; MCP host-policy and transport concerns stay documented separately under the existing MCP docs. +- Follow docs parity rules: any public README change in English must be mirrored in `README.ja.md` in the same change. +- Reuse the external `skill-creator` helper scripts for `openai.yaml` generation and lightweight validation rather than adding new repo-local validation code for this issue. + +### Verification + +- `python C:\Users\HARUMI\.codex\skills\.system\skill-creator\scripts\generate_openai_yaml.py .agents/skills/exstruct-cli --interface ...` +- `python C:\Users\HARUMI\.codex\skills\.system\skill-creator\scripts\quick_validate.py .agents/skills/exstruct-cli` +- `uv run task precommit-run` +- Manual scenario review of: + - create-vs-edit command selection + - `validate -> dry-run -> apply -> verify` guidance + - unsupported-op / backend-constraint handling + - CLI-vs-MCP routing guidance + - README English/Japanese parity + +### ADR verdict + +- `recommended` +- rationale: the change turns AI-agent operational workflow into a durable repository rule and resolves recurring tradeoffs around single-skill packaging, repo source of truth, and the CLI-versus-MCP boundary. diff --git a/tasks/lessons.md b/tasks/lessons.md index 21ff5a5..06ec87b 100644 --- a/tasks/lessons.md +++ b/tasks/lessons.md @@ -98,3 +98,7 @@ - When documenting a `dry_run -> apply` edit workflow, do not imply the same engine will run both phases under `backend="auto"`; call out the openpyxl/COM split and tell users to pin `openpyxl` when same-engine comparison matters. - When documenting CLI failure behavior, distinguish serialized `PatchResult.error` failures from pre-execution stderr failures such as JSON parse, validation, or local runtime errors. + +## 2026-03-21 skill installation docs lessons + +- When a repo-owned Skill is intended to be publicly installable from the repository, document the `npx skills add / --skill ` path as the primary install route instead of only manual copy steps. diff --git a/tasks/todo.md b/tasks/todo.md index c7c3f67..0794c6e 100644 --- a/tasks/todo.md +++ b/tasks/todo.md @@ -55,3 +55,31 @@ - `rg -n '^version = "0\.7\.1"$' pyproject.toml uv.lock` - `rg -n "^## " tasks/feature_spec.md tasks/todo.md` - `git diff --check -- CHANGELOG.md docs/release-notes/v0.7.1.md mkdocs.yml pyproject.toml uv.lock tasks/feature_spec.md tasks/todo.md` + +## 2026-03-21 issue #115 ExStruct CLI Skill + +### Planning + +- [x] Confirm the ADR verdict and draft the new policy record for the CLI Skill packaging and CLI/MCP boundary decisions. +- [x] Add an internal spec under `dev-docs/specs/` for the `exstruct-cli` Skill contract. +- [x] Create `.agents/skills/exstruct-cli/` with `SKILL.md`, `agents/openai.yaml`, and the required `references/` files. +- [x] Keep `SKILL.md` concise and move detailed command, verification, and backend guidance into `references/`. +- [x] Update `README.md` and `README.ja.md` with Skill installation guidance, when-to-use guidance, and minimal example prompts. +- [x] Run the external `skill-creator` helper scripts to generate and validate `agents/openai.yaml`. +- [x] Run repo verification (`uv run task precommit-run`) and record the result. +- [x] Review which #115 notes remain temporary versus durable, then compress the `tasks/` sections after the durable content is migrated. + +### Review + +- Added the canonical repo-owned Skill at `.agents/skills/exstruct-cli/` with a lean `SKILL.md`, five focused reference documents, and generated `agents/openai.yaml`. +- Added `dev-docs/specs/exstruct-cli-skill.md` as the durable contract for the Skill layout, trigger/positioning rules, and verification obligations. +- Added `dev-docs/adr/ADR-0009-single-cli-skill-for-agent-workflows.md` and synchronized `dev-docs/adr/README.md`, `dev-docs/adr/index.yaml`, and `dev-docs/adr/decision-map.md`. +- Updated `README.md` and `README.ja.md` with installation guidance, CLI-vs-MCP usage boundaries, and example prompts. +- The durable content for #115 now lives in `.agents/skills/exstruct-cli/`, `dev-docs/specs/exstruct-cli-skill.md`, `dev-docs/adr/ADR-0009-single-cli-skill-for-agent-workflows.md`, `README.md`, and `README.ja.md`; this `tasks/` section remains only as a compact implementation record. +- Verification: + - `python C:\Users\HARUMI\.codex\skills\.system\skill-creator\scripts\generate_openai_yaml.py .agents/skills/exstruct-cli --interface 'display_name=ExStruct CLI' --interface 'short_description=Guide safe ExStruct CLI edit workflows' --interface 'default_prompt=Use $exstruct-cli to choose the right ExStruct editing CLI command, follow a safe validate/dry-run workflow, and explain any backend constraints for this workbook task.'` + - `python C:\Users\HARUMI\.codex\skills\.system\skill-creator\scripts\quick_validate.py .agents/skills/exstruct-cli` + - `rg -n "ExStruct CLI Skill|exstruct-cli|validate -> dry-run -> apply -> verify|\.agents/skills/exstruct-cli" README.md README.ja.md dev-docs/specs/exstruct-cli-skill.md dev-docs/adr/ADR-0009-single-cli-skill-for-agent-workflows.md .agents/skills/exstruct-cli/ -g "*"` + - `rg -n "^## |Tests:|Code:|Related specs:" dev-docs/adr/ADR-0009-single-cli-skill-for-agent-workflows.md` + - `uv run task precommit-run` + - `git diff --check` From aa6c07ea4f145f0053582feec4010d69a3451c69 Mon Sep 17 00:00:00 2001 From: harumiWeb Date: Sat, 21 Mar 2026 20:43:46 +0900 Subject: [PATCH 2/5] Address review feedback for CLI skill docs --- .../references/backend-constraints.md | 13 +++++---- .../exstruct-cli/references/safe-editing.md | 28 ++++++++++++------- README.ja.md | 4 +++ README.md | 8 ++++-- dev-docs/specs/exstruct-cli-skill.md | 19 +++++++------ tasks/feature_spec.md | 4 +-- tasks/todo.md | 12 ++++---- 7 files changed, 54 insertions(+), 34 deletions(-) diff --git a/.agents/skills/exstruct-cli/references/backend-constraints.md b/.agents/skills/exstruct-cli/references/backend-constraints.md index 118d139..e6e7aee 100644 --- a/.agents/skills/exstruct-cli/references/backend-constraints.md +++ b/.agents/skills/exstruct-cli/references/backend-constraints.md @@ -6,7 +6,8 @@ capabilities. ## Backend summary - `openpyxl` - - default choice for ordinary workbook edits + - recommended backend to pin for ordinary workbook edits, especially when + you want the same engine for dry-run and apply - supports `--dry-run`, `--return-inverse-ops`, and `--preflight-formula-check` - `com` @@ -14,19 +15,21 @@ capabilities. - required for `.xls` creation/editing - `auto` - follows ExStruct's existing backend-selection policy - - can use openpyxl for a dry run and COM for the real apply + - can resolve to openpyxl for a dry-run request and COM for a later apply + request ## Constraints to call out - `create_chart` is COM-only. -- `.xls` workflows require COM and are not valid with `backend=openpyxl`. +- `.xls` workflows require COM, are not valid with `backend=openpyxl`, and do + not support `--dry-run`. - Requests that need host-owned path restrictions, transport mapping, or artifact mirroring belong to MCP, not the local CLI Skill. ## Failure behavior - State clearly when the requested backend or capability is unsupported. -- Do not pretend that `auto` guarantees the same engine across dry run and - apply. +- Do not pretend that `auto` guarantees the same engine across separate dry-run + and apply requests. - Redirect to MCP only for host-policy concerns, not as a generic substitute for unsupported CLI behavior. diff --git a/.agents/skills/exstruct-cli/references/safe-editing.md b/.agents/skills/exstruct-cli/references/safe-editing.md index c7e35df..5f00370 100644 --- a/.agents/skills/exstruct-cli/references/safe-editing.md +++ b/.agents/skills/exstruct-cli/references/safe-editing.md @@ -5,12 +5,17 @@ wrong apply would be expensive. ## Standard flow -1. Validate the input workbook when readability is uncertain. -2. Build or inspect the patch-op JSON. -3. Run `exstruct patch --dry-run` for risky edits. -4. Inspect `PatchResult`, warnings, `patch_diff`, and `engine`. -5. Re-run without `--dry-run` only after the plan is acceptable. -6. Perform lightweight verification or deeper verification based on risk. +1. Determine whether the request creates a new workbook or edits an existing + one. +2. Validate the input workbook when readability is uncertain for an existing + workbook edit. +3. Build or inspect the patch-op JSON. +4. Run `exstruct patch --dry-run` for risky edits to an existing workbook. +5. Run `exstruct make --dry-run` for risky new-workbook requests when the + chosen ops and output format support dry-run. +6. Inspect `PatchResult`, warnings, `patch_diff`, and `engine`. +7. Re-run without `--dry-run` only after the plan is acceptable. +8. Perform lightweight verification or deeper verification based on risk. ## Ambiguity rules @@ -27,10 +32,13 @@ wrong apply would be expensive. - range-wide formula fills - style changes across large regions - chart creation or COM-only workflows -- Prefer `--backend openpyxl` when you want the dry run and real apply to use - the same engine. -- Explain that `--backend auto` may use openpyxl for the dry run but COM for - the real apply on COM-capable hosts. +- `create_chart` requests and `.xls` create/edit workflows reject `--dry-run`; + inspect ops, validate what you can, and explain the backend constraint before + any non-dry-run apply. +- Prefer `--backend openpyxl` when you want the dry run and the later apply run + to use the same engine. +- Explain that `--backend auto` can resolve to openpyxl for a dry-run request + and COM for a later non-dry-run request on COM-capable hosts. ## Failure behavior diff --git a/README.ja.md b/README.ja.md index f6293a0..5b79e9a 100644 --- a/README.ja.md +++ b/README.ja.md @@ -144,6 +144,10 @@ npx skills add harumiWeb/exstruct/.agents/skills --skill exstruct-cli `ops describe` の使い分けや、安全な `validate -> dry-run -> apply -> verify` フローが必要なときに使います。 +エージェント向けの最小プロンプト例: + +> `$exstruct-cli` を使って適切な ExStruct editing CLI コマンドを選び、validate/dry-run を含む安全なフローと、このワークブック作業に関係する backend 制約を説明してください。 + ## MCPサーバー (標準入出力) MCP は同じ editing core を包む integration / compatibility layer です。 diff --git a/README.md b/README.md index 9534bd0..611284c 100644 --- a/README.md +++ b/README.md @@ -151,13 +151,17 @@ npx skills add harumiWeb/exstruct/.agents/skills --skill exstruct-cli That command should install `exstruct-cli` directly from this repository's published Skill directory. If you are working from an unpublished branch or a runtime that does not support `npx skills add`, fall back to copying the same -folder into the equivalent local skill directory that discovers `SKILL.md` -based skills. +folder into the equivalent local skill directory that discovers +`SKILL.md`-based skills. Use this Skill when the agent needs help choosing between `patch`, `make`, `validate`, `ops list`, and `ops describe`, or when it should follow the safe `validate -> dry-run -> apply -> verify` workflow. +Example prompt for agents: + +> Use `$exstruct-cli` to choose the right ExStruct editing CLI command, follow a safe validate/dry-run workflow, and explain any backend constraints for this workbook task. + ## MCP Server (stdio) MCP is the integration / compatibility layer around the same editing core. Use diff --git a/dev-docs/specs/exstruct-cli-skill.md b/dev-docs/specs/exstruct-cli-skill.md index 4c355a3..e8cb565 100644 --- a/dev-docs/specs/exstruct-cli-skill.md +++ b/dev-docs/specs/exstruct-cli-skill.md @@ -13,9 +13,9 @@ Skill that teaches AI agents how to use the existing ExStruct editing CLI. ## Non-goals -- No change to CLI, Python API, or MCP runtime behavior. -- No `.claude/skills/` mirror or sync automation in the repository. -- No requirement to add Skill-local `scripts/` or `assets/` in the initial +- Keep CLI, Python API, and MCP runtime behavior unchanged. +- Do not add `.claude/skills/` mirror or sync automation in the repository. +- Leave Skill-local `scripts/` and `assets/` optional in the initial implementation. ## Canonical repo layout @@ -82,9 +82,9 @@ Skill that teaches AI agents how to use the existing ExStruct editing CLI. ### `references/verify-workflows.md` -- Define what to inspect in `PatchResult`. -- Define when re-validation or re-extraction is required. -- Define when lightweight verification is acceptable. +- Specify what to inspect in `PatchResult`. +- Establish when re-validation or re-extraction is required. +- Clarify when lightweight verification is acceptable. ### `references/backend-constraints.md` @@ -115,9 +115,10 @@ Skill that teaches AI agents how to use the existing ExStruct editing CLI. ## Verification obligations -- Validate the Skill folder with: - - `generate_openai_yaml.py` - - `quick_validate.py` +- Run verification from the repository root with explicit commands against + `.agents/skills/exstruct-cli`: + - `python /scripts/generate_openai_yaml.py .agents/skills/exstruct-cli --interface ...` + - `python /scripts/quick_validate.py .agents/skills/exstruct-cli` - Run `uv run task precommit-run`. - Manually review representative scenarios for: - create versus edit routing diff --git a/tasks/feature_spec.md b/tasks/feature_spec.md index bd89550..03fdf2c 100644 --- a/tasks/feature_spec.md +++ b/tasks/feature_spec.md @@ -154,8 +154,8 @@ ### Verification -- `python C:\Users\HARUMI\.codex\skills\.system\skill-creator\scripts\generate_openai_yaml.py .agents/skills/exstruct-cli --interface ...` -- `python C:\Users\HARUMI\.codex\skills\.system\skill-creator\scripts\quick_validate.py .agents/skills/exstruct-cli` +- `python /scripts/generate_openai_yaml.py .agents/skills/exstruct-cli --interface ...` +- `python /scripts/quick_validate.py .agents/skills/exstruct-cli` - `uv run task precommit-run` - Manual scenario review of: - create-vs-edit command selection diff --git a/tasks/todo.md b/tasks/todo.md index 0794c6e..6475833 100644 --- a/tasks/todo.md +++ b/tasks/todo.md @@ -71,14 +71,14 @@ ### Review -- Added the canonical repo-owned Skill at `.agents/skills/exstruct-cli/` with a lean `SKILL.md`, five focused reference documents, and generated `agents/openai.yaml`. -- Added `dev-docs/specs/exstruct-cli-skill.md` as the durable contract for the Skill layout, trigger/positioning rules, and verification obligations. -- Added `dev-docs/adr/ADR-0009-single-cli-skill-for-agent-workflows.md` and synchronized `dev-docs/adr/README.md`, `dev-docs/adr/index.yaml`, and `dev-docs/adr/decision-map.md`. -- Updated `README.md` and `README.ja.md` with installation guidance, CLI-vs-MCP usage boundaries, and example prompts. +- Introduced the canonical repo-owned Skill at `.agents/skills/exstruct-cli/` with a lean `SKILL.md`, five focused reference documents, and generated `agents/openai.yaml`. +- Published `dev-docs/specs/exstruct-cli-skill.md` as the durable contract for the Skill layout, trigger/positioning rules, and verification obligations. +- Documented the policy decision in `dev-docs/adr/ADR-0009-single-cli-skill-for-agent-workflows.md` and synchronized `dev-docs/adr/README.md`, `dev-docs/adr/index.yaml`, and `dev-docs/adr/decision-map.md`. +- Expanded `README.md` and `README.ja.md` with installation guidance, CLI-vs-MCP usage boundaries, and example prompts. - The durable content for #115 now lives in `.agents/skills/exstruct-cli/`, `dev-docs/specs/exstruct-cli-skill.md`, `dev-docs/adr/ADR-0009-single-cli-skill-for-agent-workflows.md`, `README.md`, and `README.ja.md`; this `tasks/` section remains only as a compact implementation record. - Verification: - - `python C:\Users\HARUMI\.codex\skills\.system\skill-creator\scripts\generate_openai_yaml.py .agents/skills/exstruct-cli --interface 'display_name=ExStruct CLI' --interface 'short_description=Guide safe ExStruct CLI edit workflows' --interface 'default_prompt=Use $exstruct-cli to choose the right ExStruct editing CLI command, follow a safe validate/dry-run workflow, and explain any backend constraints for this workbook task.'` - - `python C:\Users\HARUMI\.codex\skills\.system\skill-creator\scripts\quick_validate.py .agents/skills/exstruct-cli` + - `python /scripts/generate_openai_yaml.py .agents/skills/exstruct-cli --interface 'display_name=ExStruct CLI' --interface 'short_description=Guide safe ExStruct CLI edit workflows' --interface 'default_prompt=Use $exstruct-cli to choose the right ExStruct editing CLI command, follow a safe validate/dry-run workflow, and explain any backend constraints for this workbook task.'` + - `python /scripts/quick_validate.py .agents/skills/exstruct-cli` - `rg -n "ExStruct CLI Skill|exstruct-cli|validate -> dry-run -> apply -> verify|\.agents/skills/exstruct-cli" README.md README.ja.md dev-docs/specs/exstruct-cli-skill.md dev-docs/adr/ADR-0009-single-cli-skill-for-agent-workflows.md .agents/skills/exstruct-cli/ -g "*"` - `rg -n "^## |Tests:|Code:|Related specs:" dev-docs/adr/ADR-0009-single-cli-skill-for-agent-workflows.md` - `uv run task precommit-run` From 26428bb43d682c02130b2b3b95b30582b45505a7 Mon Sep 17 00:00:00 2001 From: harumiWeb Date: Sat, 21 Mar 2026 20:48:39 +0900 Subject: [PATCH 3/5] Polish Japanese skill installation wording --- README.ja.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.ja.md b/README.ja.md index 5b79e9a..7ad2cec 100644 --- a/README.ja.md +++ b/README.ja.md @@ -137,8 +137,8 @@ npx skills add harumiWeb/exstruct/.agents/skills --skill exstruct-cli このコマンドは、このリポジトリで公開される Skill ディレクトリから `exstruct-cli` を直接追加する想定です。まだ未公開ブランチで作業している場合や、 -`npx skills add` を使えない実行環境では、従来どおり `SKILL.md` ベースの Skill を -検出するローカルディレクトリへ同じフォルダを手動配置してください。 +`npx skills add` を使えない実行環境では、従来どおり `SKILL.md` ベースの Skill が +検出されるローカルディレクトリへ同じフォルダを手動配置してください。 この Skill は、`patch` / `make` / `validate` / `ops list` / `ops describe` の使い分けや、安全な From 31184df2a14b7b76b34c7df7fc2ab7bccf52ce2a Mon Sep 17 00:00:00 2001 From: harumiWeb Date: Sat, 21 Mar 2026 21:03:21 +0900 Subject: [PATCH 4/5] Clarify skill verification flag limits --- .../skills/exstruct-cli/references/backend-constraints.md | 6 ++++-- .agents/skills/exstruct-cli/references/safe-editing.md | 7 ++++--- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/.agents/skills/exstruct-cli/references/backend-constraints.md b/.agents/skills/exstruct-cli/references/backend-constraints.md index e6e7aee..72f04fd 100644 --- a/.agents/skills/exstruct-cli/references/backend-constraints.md +++ b/.agents/skills/exstruct-cli/references/backend-constraints.md @@ -20,9 +20,11 @@ capabilities. ## Constraints to call out -- `create_chart` is COM-only. +- `create_chart` is COM-only and does not support `--dry-run`, + `--return-inverse-ops`, or `--preflight-formula-check`. - `.xls` workflows require COM, are not valid with `backend=openpyxl`, and do - not support `--dry-run`. + not support `--dry-run`, `--return-inverse-ops`, or + `--preflight-formula-check`. - Requests that need host-owned path restrictions, transport mapping, or artifact mirroring belong to MCP, not the local CLI Skill. diff --git a/.agents/skills/exstruct-cli/references/safe-editing.md b/.agents/skills/exstruct-cli/references/safe-editing.md index 5f00370..afc50d9 100644 --- a/.agents/skills/exstruct-cli/references/safe-editing.md +++ b/.agents/skills/exstruct-cli/references/safe-editing.md @@ -32,9 +32,10 @@ wrong apply would be expensive. - range-wide formula fills - style changes across large regions - chart creation or COM-only workflows -- `create_chart` requests and `.xls` create/edit workflows reject `--dry-run`; - inspect ops, validate what you can, and explain the backend constraint before - any non-dry-run apply. +- `create_chart` requests and `.xls` create/edit workflows do not support + `--dry-run`, `--return-inverse-ops`, or `--preflight-formula-check`; + inspect ops, run only supported validation, and explain the backend + constraint before any non-dry-run apply. - Prefer `--backend openpyxl` when you want the dry run and the later apply run to use the same engine. - Explain that `--backend auto` can resolve to openpyxl for a dry-run request From d8e803569cd195b3a44c97ac56b687f41f5b10b4 Mon Sep 17 00:00:00 2001 From: harumiWeb Date: Sat, 21 Mar 2026 21:14:46 +0900 Subject: [PATCH 5/5] Align skill docs with inspect-first flow --- .agents/skills/exstruct-cli/agents/openai.yaml | 2 +- README.ja.md | 5 +++-- README.md | 4 ++-- tasks/feature_spec.md | 2 +- tasks/todo.md | 4 ++-- 5 files changed, 9 insertions(+), 8 deletions(-) diff --git a/.agents/skills/exstruct-cli/agents/openai.yaml b/.agents/skills/exstruct-cli/agents/openai.yaml index 7114e7d..9c8712d 100644 --- a/.agents/skills/exstruct-cli/agents/openai.yaml +++ b/.agents/skills/exstruct-cli/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "ExStruct CLI" short_description: "Guide safe ExStruct CLI edit workflows" - default_prompt: "Use $exstruct-cli to choose the right ExStruct editing CLI command, follow a safe validate/dry-run workflow, and explain any backend constraints for this workbook task." + default_prompt: "Use $exstruct-cli to choose the right ExStruct editing CLI command, follow a safe validate/dry-run workflow that inspects the PatchResult/diff before applying changes, and explain any backend constraints for this workbook task." diff --git a/README.ja.md b/README.ja.md index 7ad2cec..188a9ef 100644 --- a/README.ja.md +++ b/README.ja.md @@ -142,11 +142,12 @@ npx skills add harumiWeb/exstruct/.agents/skills --skill exstruct-cli この Skill は、`patch` / `make` / `validate` / `ops list` / `ops describe` の使い分けや、安全な -`validate -> dry-run -> apply -> verify` フローが必要なときに使います。 +`validate -> dry-run -> PatchResult/diff を確認 -> apply -> verify` +フローが必要なときに使います。 エージェント向けの最小プロンプト例: -> `$exstruct-cli` を使って適切な ExStruct editing CLI コマンドを選び、validate/dry-run を含む安全なフローと、このワークブック作業に関係する backend 制約を説明してください。 +> `$exstruct-cli` を使って適切な ExStruct editing CLI コマンドを選び、PatchResult/diff の確認を含む validate/dry-run の安全なフローと、このワークブック作業に関係する backend 制約を説明してください。 ## MCPサーバー (標準入出力) diff --git a/README.md b/README.md index 611284c..4e72604 100644 --- a/README.md +++ b/README.md @@ -156,11 +156,11 @@ folder into the equivalent local skill directory that discovers Use this Skill when the agent needs help choosing between `patch`, `make`, `validate`, `ops list`, and `ops describe`, or when it should follow the safe -`validate -> dry-run -> apply -> verify` workflow. +`validate -> dry-run -> inspect -> apply -> verify` workflow. Example prompt for agents: -> Use `$exstruct-cli` to choose the right ExStruct editing CLI command, follow a safe validate/dry-run workflow, and explain any backend constraints for this workbook task. +> Use `$exstruct-cli` to choose the right ExStruct editing CLI command, follow a safe validate/dry-run/inspect workflow, and explain any backend constraints for this workbook task. ## MCP Server (stdio) diff --git a/tasks/feature_spec.md b/tasks/feature_spec.md index 03fdf2c..2252969 100644 --- a/tasks/feature_spec.md +++ b/tasks/feature_spec.md @@ -159,7 +159,7 @@ - `uv run task precommit-run` - Manual scenario review of: - create-vs-edit command selection - - `validate -> dry-run -> apply -> verify` guidance + - `validate -> dry-run -> inspect -> apply -> verify` guidance - unsupported-op / backend-constraint handling - CLI-vs-MCP routing guidance - README English/Japanese parity diff --git a/tasks/todo.md b/tasks/todo.md index 6475833..3732bb1 100644 --- a/tasks/todo.md +++ b/tasks/todo.md @@ -77,9 +77,9 @@ - Expanded `README.md` and `README.ja.md` with installation guidance, CLI-vs-MCP usage boundaries, and example prompts. - The durable content for #115 now lives in `.agents/skills/exstruct-cli/`, `dev-docs/specs/exstruct-cli-skill.md`, `dev-docs/adr/ADR-0009-single-cli-skill-for-agent-workflows.md`, `README.md`, and `README.ja.md`; this `tasks/` section remains only as a compact implementation record. - Verification: - - `python /scripts/generate_openai_yaml.py .agents/skills/exstruct-cli --interface 'display_name=ExStruct CLI' --interface 'short_description=Guide safe ExStruct CLI edit workflows' --interface 'default_prompt=Use $exstruct-cli to choose the right ExStruct editing CLI command, follow a safe validate/dry-run workflow, and explain any backend constraints for this workbook task.'` + - `python /scripts/generate_openai_yaml.py .agents/skills/exstruct-cli --interface 'display_name=ExStruct CLI' --interface 'short_description=Guide safe ExStruct CLI edit workflows' --interface 'default_prompt=Use $exstruct-cli to choose the right ExStruct editing CLI command, follow a safe validate/dry-run workflow that inspects the PatchResult/diff before applying changes, and explain any backend constraints for this workbook task.'` - `python /scripts/quick_validate.py .agents/skills/exstruct-cli` - - `rg -n "ExStruct CLI Skill|exstruct-cli|validate -> dry-run -> apply -> verify|\.agents/skills/exstruct-cli" README.md README.ja.md dev-docs/specs/exstruct-cli-skill.md dev-docs/adr/ADR-0009-single-cli-skill-for-agent-workflows.md .agents/skills/exstruct-cli/ -g "*"` + - `rg -n "ExStruct CLI Skill|exstruct-cli|validate -> dry-run -> inspect -> apply -> verify|\.agents/skills/exstruct-cli" README.md README.ja.md dev-docs/specs/exstruct-cli-skill.md dev-docs/adr/ADR-0009-single-cli-skill-for-agent-workflows.md .agents/skills/exstruct-cli/ -g "*"` - `rg -n "^## |Tests:|Code:|Related specs:" dev-docs/adr/ADR-0009-single-cli-skill-for-agent-workflows.md` - `uv run task precommit-run` - `git diff --check`