@heihei0299/matt-skills 1.0.0 → 1.1.1

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/README.md

@@ -9,7 +9,7 @@ template/
 ├── AGENTS.md         项目级全局配置（行为路由 + 分文件指针）
 ├── .pi/              pi-agent 项目配置（pi 标准结构：`.pi/skills/` 直放独有技能，自动发现）
 └── .opencode/        分发内容（目标仓库的 opencode 项目配置）
-    ├── skills/       4 个独有技能（tdd-implement、grill-to-spec、diagnose-fix、commit-check）
+    ├── skills/       5 个独有技能（tdd-implement、grill-to-spec、diagnose-fix、commit-check、instance-test）
     ├── agents/       issue-audit 子代理定义
     ├── commands/     issue-audit + 9 个显式触发技能命令（grill-to-spec/wayfinder/to-spec/to-tickets/triage/improve-codebase-architecture/teach/handoff/writing-great-skills）
     ├── docs/agents/  5 个分文件（运行时纪律 / 技能设计 / issue tracker / triage labels / domain）
@@ -160,8 +160,11 @@ npm publish
 ## 开发
 
 ```sh
-npm test
+npm test                          # 全量测试 122 项
+npm run build:template            # 从单源生成 template/.opencode/.pi（config/proprietary.json 为单一事实源）
 ```
 
-交互模式依赖 `prompts`（见 `package.json`）；测试见 `test/cli.test.js`。
+交互模式依赖 `prompts`（见 `package.json`）；测试见 `test/cli.test.js`、`test/cli-init.test.js`、`test/template-sync.test.js`。
+
+用户手动触发的功能测试：`/instance-test`（见 `.agents/skills/instance-test/SKILL.md`）——在隔离 `temp dir` 跑 prompt 实例验实际功能，`references/instances.md` 为通用模板。
 

package/bin/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readdir, readFile, cp, stat } from 'node:fs/promises';
+import { readdir, readFile, cp, stat, writeFile, mkdir } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -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;
@@ -88,6 +88,21 @@ async function backupIfExists(p) {
   return bak;
 }
 
+async function ensureSkillsGitignore(skillsDir) {
+  try {
+    await mkdir(skillsDir, { recursive: true });
+    const gi = path.join(skillsDir, '.gitignore');
+    const content = '# matt-skills backup — pi skips .bak via explicit filter + this fallback\n*.bak\n*.bak/\n';
+    if (await pathExists(gi)) {
+      const cur = await readFile(gi, 'utf8');
+      if (cur.includes('*.bak')) return;
+      await writeFile(gi, cur.endsWith('\n') ? `${cur}${content}` : `${cur}\n${content}`);
+    } else {
+      await writeFile(gi, content);
+    }
+  } catch {}
+}
+
 const TOOLS = ['codex', 'pi', 'opencode', 'claude'];
 
 const PROJECT_DIRS = {
@@ -219,6 +234,7 @@ async function initCommand({ dest, force }) {
   } else {
     process.stdout.write(`上游技能：已装 ${installed}、跳过 ${skipped}\n`);
   }
+  await ensureSkillsGitignore(skillsDir);
   process.stdout.write(`目标路径：${target}\n`);
 }
 
@@ -275,6 +291,7 @@ async function syncCommand({ dest, force }) {
   } else {
     process.stdout.write(`上游技能：新增 ${installed}、更新 ${updated}\n`);
   }
+  await ensureSkillsGitignore(skillsDir);
   process.stdout.write(`目标路径：${target}\n`);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heihei0299/matt-skills",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "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.