@heihei0299/matt-skills 1.0.0 → 1.1.0

package/.agents/skills/instance-test/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: instance-test
+disable-model-invocation: true
+description: "Verify project meets expected goals by running prompt instances in isolated temp dirs"
+---
+
+# Instance Test
+
+Run **instance** prompts to verify project meets expected goals via actual functional tests. Each **instance** is a prompt + expected outcome, executed in an isolated temp dir — no mocks, no stubs.
+
+## Steps
+
+### 1. Gather instances
+
+Collect the **instance** set to run:
+
+- User-provided instances (prompt, command, expected files/stdout/exit code), or
+- Derived from `spec.md`/`README` acceptance criteria — extract each verifiable behavior as one instance, then confirm the list with the user before running.
+
+Each **instance** must declare: command to run, expected files/content, expected stdout phrases, expected exit code.
+
+Completion: instance list is fixed (prompt, expected outcome, verification command) — no instance is added mid-run.
+
+### 2. Run instances
+
+For each **instance** in order:
+
+1. `mktemp -d` isolated dir (or `git worktree` / `--dest` if the project supports it).
+2. Execute the instance's command — capture stdout/stderr and exit code.
+3. Snapshot result files and side effects declared in expected.
+
+Do not run instances in parallel — one **instance** at a time, so failures are isolated and artifacts do not collide.
+
+Completion: every **instance** has a run dir with captured output and file snapshot.
+
+### 3. Evaluate
+
+Compare each **instance**'s actual vs expected:
+
+- File existence/content (`test -f`, `grep -q`, `diff`).
+- Stdout/stderr contains expected phrases.
+- Exit code matches expected.
+
+Mark `PASS`/`FAIL` per **instance** with evidence (file path, stdout line, or diff).
+
+Completion: every **instance** has a `PASS` or `FAIL` with evidence — no unevaluated instance.
+
+### 4. Report
+
+Summarize in conversation:
+
+- `PASS m/n` with per-instance evidence.
+- Failures list the gap (expected vs actual) and the run dir for reproduction.
+- Clean up temp dirs unless `--keep` is requested.
+
+Do not write a report file (`report-*.md`) — output stays in conversation. Keep temp dirs only on failure for debugging.
+
+## References
+
+- Instance definitions (if any): `references/instances.md` — example set, auto-loaded only when present, not required.
+- Project expected behavior: `spec.md`/`README`/`--help` — the source of truth for what to verify.

package/.agents/skills/instance-test/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Instance Test"
+  short_description: "Verify project via prompt instances in isolated temp projects"
+policy:
+  allow_implicit_invocation: false

package/.agents/skills/instance-test/references/instances.md

@@ -0,0 +1,45 @@
+# Instances template
+
+Generic template for **instance** functional tests. Each **instance** is a prompt + command + expected outcome. Copy and adapt for your project; the example below is for `matt-skills`.
+
+## Format
+
+Each instance declares:
+
+- Prompt: human intent (what to verify)
+- Command: shell command to run in isolated dir
+- Expected: files/content, stdout phrases, exit code
+
+Verification commands are in `SKILL.md` steps.
+
+## Example: matt-skills functional behavior
+
+### 1. Fresh init
+Prompt: verify fresh project initialization
+Command: `node bin/cli.js init --dest <tmp>`
+Expected: `AGENTS.md`, `.opencode/skills/tdd-implement/SKILL.md`, `.pi/skills/tdd-implement/SKILL.md`, `.agents/skills/tdd` (22 upstream) exist; stdout `模板：已复制` + `上游技能：已装 22`; no `.bak`; exit 0.
+
+### 2. Init skip on existing
+Prompt: verify idempotent init without --force
+Command: `init` twice without `--force`, second with local edit to `AGENTS.md`
+Expected: second stdout `模板已存在.*跳过`, `上游技能：已装 0、跳过 22`; local edit preserved; exit 0.
+
+### 3. Init --force with backup
+Prompt: verify forced init backs up
+Command: `init --force --dest <tmp>` after local edit
+Expected: stdout `已备份` + `备份 22`; `AGENTS.md.bak` exists with local edit; `AGENTS.md` restored from template; `.agents/skills/tdd.bak` exists; exit 0.
+
+### 4. Sync on existing
+Prompt: verify sync backs up existing project
+Command: `sync --dest <tmp>` after local edit
+Expected: stdout `同步` + `已备份`; `AGENTS.md.bak` exists; exit 0.
+
+### 5. Sync --force without backup
+Prompt: verify sync --force does not backup
+Command: `sync --force --dest <tmp>`
+Expected: stdout `已覆盖` without new `.bak`; exit 0.
+
+### 6. List
+Prompt: verify skill listing
+Command: `list` and `list --json`
+Expected: 27 skills, includes `tdd` with correct description; `--json` is valid JSON array; exit 0.

package/bin/cli.js

@@ -7,7 +7,7 @@ import prompts from 'prompts';
 
 const SKILLS_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '.agents', 'skills');
 const TEMPLATE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'template');
-const PROPRIETARY_SKILLS = new Set(['tdd-implement', 'grill-to-spec', 'diagnose-fix', 'commit-check']);
+const PROPRIETARY_SKILLS = new Set(['tdd-implement', 'grill-to-spec', 'diagnose-fix', 'commit-check', 'instance-test']);
 process.stdout.on('error', (err) => {
   if (err.code === 'EPIPE') process.exit(0);
   throw err;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heihei0299/matt-skills",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Agent skills + 项目配置模板：一条命令初始化 opencode / pi-agent 项目（含 mattpocock/skills 上游技能）",
   "type": "module",
   "bin": {
@@ -14,7 +14,8 @@
   ],
   "scripts": {
     "test": "node --test test/*.test.js",
-    "prepublishOnly": "node --test test/*.test.js"
+    "prepublishOnly": "node --test test/*.test.js",
+    "build:template": "node scripts/build-template.js"
   },
   "dependencies": {
     "prompts": "^2.4.2"

package/template/.opencode/skills/instance-test/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: instance-test
+disable-model-invocation: true
+description: "Verify project meets expected goals by running prompt instances in isolated temp dirs"
+---
+
+# Instance Test
+
+Run **instance** prompts to verify project meets expected goals via actual functional tests. Each **instance** is a prompt + expected outcome, executed in an isolated temp dir — no mocks, no stubs.
+
+## Steps
+
+### 1. Gather instances
+
+Collect the **instance** set to run:
+
+- User-provided instances (prompt, command, expected files/stdout/exit code), or
+- Derived from `spec.md`/`README` acceptance criteria — extract each verifiable behavior as one instance, then confirm the list with the user before running.
+
+Each **instance** must declare: command to run, expected files/content, expected stdout phrases, expected exit code.
+
+Completion: instance list is fixed (prompt, expected outcome, verification command) — no instance is added mid-run.
+
+### 2. Run instances
+
+For each **instance** in order:
+
+1. `mktemp -d` isolated dir (or `git worktree` / `--dest` if the project supports it).
+2. Execute the instance's command — capture stdout/stderr and exit code.
+3. Snapshot result files and side effects declared in expected.
+
+Do not run instances in parallel — one **instance** at a time, so failures are isolated and artifacts do not collide.
+
+Completion: every **instance** has a run dir with captured output and file snapshot.
+
+### 3. Evaluate
+
+Compare each **instance**'s actual vs expected:
+
+- File existence/content (`test -f`, `grep -q`, `diff`).
+- Stdout/stderr contains expected phrases.
+- Exit code matches expected.
+
+Mark `PASS`/`FAIL` per **instance** with evidence (file path, stdout line, or diff).
+
+Completion: every **instance** has a `PASS` or `FAIL` with evidence — no unevaluated instance.
+
+### 4. Report
+
+Summarize in conversation:
+
+- `PASS m/n` with per-instance evidence.
+- Failures list the gap (expected vs actual) and the run dir for reproduction.
+- Clean up temp dirs unless `--keep` is requested.
+
+Do not write a report file (`report-*.md`) — output stays in conversation. Keep temp dirs only on failure for debugging.
+
+## References
+
+- Instance definitions (if any): `references/instances.md` — example set, auto-loaded only when present, not required.
+- Project expected behavior: `spec.md`/`README`/`--help` — the source of truth for what to verify.

package/template/.opencode/skills/instance-test/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Instance Test"
+  short_description: "Verify project via prompt instances in isolated temp projects"
+policy:
+  allow_implicit_invocation: false

package/template/.opencode/skills/instance-test/references/instances.md

@@ -0,0 +1,45 @@
+# Instances template
+
+Generic template for **instance** functional tests. Each **instance** is a prompt + command + expected outcome. Copy and adapt for your project; the example below is for `matt-skills`.
+
+## Format
+
+Each instance declares:
+
+- Prompt: human intent (what to verify)
+- Command: shell command to run in isolated dir
+- Expected: files/content, stdout phrases, exit code
+
+Verification commands are in `SKILL.md` steps.
+
+## Example: matt-skills functional behavior
+
+### 1. Fresh init
+Prompt: verify fresh project initialization
+Command: `node bin/cli.js init --dest <tmp>`
+Expected: `AGENTS.md`, `.opencode/skills/tdd-implement/SKILL.md`, `.pi/skills/tdd-implement/SKILL.md`, `.agents/skills/tdd` (22 upstream) exist; stdout `模板：已复制` + `上游技能：已装 22`; no `.bak`; exit 0.
+
+### 2. Init skip on existing
+Prompt: verify idempotent init without --force
+Command: `init` twice without `--force`, second with local edit to `AGENTS.md`
+Expected: second stdout `模板已存在.*跳过`, `上游技能：已装 0、跳过 22`; local edit preserved; exit 0.
+
+### 3. Init --force with backup
+Prompt: verify forced init backs up
+Command: `init --force --dest <tmp>` after local edit
+Expected: stdout `已备份` + `备份 22`; `AGENTS.md.bak` exists with local edit; `AGENTS.md` restored from template; `.agents/skills/tdd.bak` exists; exit 0.
+
+### 4. Sync on existing
+Prompt: verify sync backs up existing project
+Command: `sync --dest <tmp>` after local edit
+Expected: stdout `同步` + `已备份`; `AGENTS.md.bak` exists; exit 0.
+
+### 5. Sync --force without backup
+Prompt: verify sync --force does not backup
+Command: `sync --force --dest <tmp>`
+Expected: stdout `已覆盖` without new `.bak`; exit 0.
+
+### 6. List
+Prompt: verify skill listing
+Command: `list` and `list --json`
+Expected: 27 skills, includes `tdd` with correct description; `--json` is valid JSON array; exit 0.

package/template/.pi/skills/instance-test/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: instance-test
+disable-model-invocation: true
+description: "Verify project meets expected goals by running prompt instances in isolated temp dirs"
+---
+
+# Instance Test
+
+Run **instance** prompts to verify project meets expected goals via actual functional tests. Each **instance** is a prompt + expected outcome, executed in an isolated temp dir — no mocks, no stubs.
+
+## Steps
+
+### 1. Gather instances
+
+Collect the **instance** set to run:
+
+- User-provided instances (prompt, command, expected files/stdout/exit code), or
+- Derived from `spec.md`/`README` acceptance criteria — extract each verifiable behavior as one instance, then confirm the list with the user before running.
+
+Each **instance** must declare: command to run, expected files/content, expected stdout phrases, expected exit code.
+
+Completion: instance list is fixed (prompt, expected outcome, verification command) — no instance is added mid-run.
+
+### 2. Run instances
+
+For each **instance** in order:
+
+1. `mktemp -d` isolated dir (or `git worktree` / `--dest` if the project supports it).
+2. Execute the instance's command — capture stdout/stderr and exit code.
+3. Snapshot result files and side effects declared in expected.
+
+Do not run instances in parallel — one **instance** at a time, so failures are isolated and artifacts do not collide.
+
+Completion: every **instance** has a run dir with captured output and file snapshot.
+
+### 3. Evaluate
+
+Compare each **instance**'s actual vs expected:
+
+- File existence/content (`test -f`, `grep -q`, `diff`).
+- Stdout/stderr contains expected phrases.
+- Exit code matches expected.
+
+Mark `PASS`/`FAIL` per **instance** with evidence (file path, stdout line, or diff).
+
+Completion: every **instance** has a `PASS` or `FAIL` with evidence — no unevaluated instance.
+
+### 4. Report
+
+Summarize in conversation:
+
+- `PASS m/n` with per-instance evidence.
+- Failures list the gap (expected vs actual) and the run dir for reproduction.
+- Clean up temp dirs unless `--keep` is requested.
+
+Do not write a report file (`report-*.md`) — output stays in conversation. Keep temp dirs only on failure for debugging.
+
+## References
+
+- Instance definitions (if any): `references/instances.md` — example set, auto-loaded only when present, not required.
+- Project expected behavior: `spec.md`/`README`/`--help` — the source of truth for what to verify.

package/template/.pi/skills/instance-test/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Instance Test"
+  short_description: "Verify project via prompt instances in isolated temp projects"
+policy:
+  allow_implicit_invocation: false

package/template/.pi/skills/instance-test/references/instances.md

@@ -0,0 +1,45 @@
+# Instances template
+
+Generic template for **instance** functional tests. Each **instance** is a prompt + command + expected outcome. Copy and adapt for your project; the example below is for `matt-skills`.
+
+## Format
+
+Each instance declares:
+
+- Prompt: human intent (what to verify)
+- Command: shell command to run in isolated dir
+- Expected: files/content, stdout phrases, exit code
+
+Verification commands are in `SKILL.md` steps.
+
+## Example: matt-skills functional behavior
+
+### 1. Fresh init
+Prompt: verify fresh project initialization
+Command: `node bin/cli.js init --dest <tmp>`
+Expected: `AGENTS.md`, `.opencode/skills/tdd-implement/SKILL.md`, `.pi/skills/tdd-implement/SKILL.md`, `.agents/skills/tdd` (22 upstream) exist; stdout `模板：已复制` + `上游技能：已装 22`; no `.bak`; exit 0.
+
+### 2. Init skip on existing
+Prompt: verify idempotent init without --force
+Command: `init` twice without `--force`, second with local edit to `AGENTS.md`
+Expected: second stdout `模板已存在.*跳过`, `上游技能：已装 0、跳过 22`; local edit preserved; exit 0.
+
+### 3. Init --force with backup
+Prompt: verify forced init backs up
+Command: `init --force --dest <tmp>` after local edit
+Expected: stdout `已备份` + `备份 22`; `AGENTS.md.bak` exists with local edit; `AGENTS.md` restored from template; `.agents/skills/tdd.bak` exists; exit 0.
+
+### 4. Sync on existing
+Prompt: verify sync backs up existing project
+Command: `sync --dest <tmp>` after local edit
+Expected: stdout `同步` + `已备份`; `AGENTS.md.bak` exists; exit 0.
+
+### 5. Sync --force without backup
+Prompt: verify sync --force does not backup
+Command: `sync --force --dest <tmp>`
+Expected: stdout `已覆盖` without new `.bak`; exit 0.
+
+### 6. List
+Prompt: verify skill listing
+Command: `list` and `list --json`
+Expected: 27 skills, includes `tdd` with correct description; `--json` is valid JSON array; exit 0.