create-yss-spec 1.1.3 → 2.0.0

package/README.md

@@ -27,6 +27,10 @@ npx create-yss-spec@latest
 - `sync` 子命令
 - 基于 `.yss-template.json` 的模板版本基线
 - 已有模板实例仓库的受管模板资产同步
+- 初始化时将 `yss-project.yaml` 从 `template-source` 改写为 `project-instance`
+- 升级时迁移 Spec / Ticket 路径并删除 `to-prd`、`to-issues` 旧 skill
+- 旧、新资产内容冲突或清单 schema / mode 非法时 fail closed
+- 保留模板的共享 skill 投影；生成实例可在尚未 `git init` 时运行模板校验
 
 ## 同步已有模板实例仓库
 
@@ -48,10 +52,14 @@ npx create-yss-spec@latest sync --dry-run
 - 默认只更新未被本地修改的受管模板文件
 - 对本地已修改文件只提示和跳过，不自动覆盖
 - 对模板已删除文件只报告，不自动删除
+- 对已知的 Spec / Ticket 旧路径执行一次性迁移
+- 迁移目标已存在且内容不一致时停止，不静默覆盖
 
 ## 开发验证
 
-在仓库根目录执行：
+CLI 源码和研发记录由本仓库独立维护。首次测试会从
+[`iloveZzz/yss-spec-project-template`](https://github.com/iloveZzz/yss-spec-project-template)
+同步受管模板快照：
 
 ```bash
 npm test
@@ -60,6 +68,16 @@ npm test
 发布前可检查打包结果：
 
 ```bash
-cd packages/create-yss-spec
 npm pack --dry-run
 ```
+
+## 研发记录
+
+- [初始化 CLI Discovery](docs/discovery/yss-spec-cli-init-discovery.md)
+- [模板同步 Discovery](docs/discovery/yss-spec-cli-template-sync-discovery.md)
+- [初始化 CLI PRD](docs/requirements/yss-spec-cli-init-prd.md)
+- [模板同步 PRD](docs/requirements/yss-spec-cli-template-sync-prd.md)
+- [垂直切片](docs/requirements/issues/)
+- [`yss-project.yaml` 跨仓库实现记录](docs/implementation/yss-project-repository-mode-contract.md)
+- [实施路由与 Build Architecture Checklist](docs/implementation/)
+- [完整中文使用手册](docs/user-guide/create-yss-spec-cli-guide.md)

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "create-yss-spec",
-  "version": "1.1.3",
+  "version": "2.0.0",
   "description": "Initialize a YSS spec project template repository",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iloveZzz/create-yss-spec.git"
+  },
+  "homepage": "https://github.com/iloveZzz/create-yss-spec#readme",
+  "bugs": {
+    "url": "https://github.com/iloveZzz/create-yss-spec/issues"
+  },
   "files": [
     "bin",
     "src",
@@ -12,6 +20,9 @@
     "create-yss-spec": "./bin/create-yss-spec.js"
   },
   "scripts": {
-    "prepack": "node ../../scripts/sync-cli-template.js"
+    "sync-template": "node scripts/sync-template.js",
+    "pretest": "npm run sync-template",
+    "test": "node --test tests/*.test.js",
+    "prepack": "npm run sync-template"
   }
 }

package/src/cli.js

@@ -9,18 +9,9 @@ const PACKAGE_MANIFEST = JSON.parse(
   fs.readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8"),
 );
 const BUNDLED_TEMPLATE_ROOT = path.join(PACKAGE_ROOT, "template");
-const REPO_TEMPLATE_ROOT = path.resolve(PACKAGE_ROOT, "../..");
-const REPO_MANIFEST_PATH = path.join(REPO_TEMPLATE_ROOT, "template.manifest.json");
 const BUNDLED_MANIFEST_PATH = path.join(PACKAGE_ROOT, "template.manifest.json");
-const IS_REPO_DEVELOPMENT =
-  fs.existsSync(path.join(REPO_TEMPLATE_ROOT, "AGENTS.md")) &&
-  fs.existsSync(REPO_MANIFEST_PATH);
-const TEMPLATE_ROOT = IS_REPO_DEVELOPMENT
-  ? REPO_TEMPLATE_ROOT
-  : BUNDLED_TEMPLATE_ROOT;
-const TEMPLATE_MANIFEST_PATH = IS_REPO_DEVELOPMENT
-  ? REPO_MANIFEST_PATH
-  : BUNDLED_MANIFEST_PATH;
+const TEMPLATE_ROOT = BUNDLED_TEMPLATE_ROOT;
+const TEMPLATE_MANIFEST_PATH = BUNDLED_MANIFEST_PATH;
 const TEMPLATE_MANIFEST_TEXT = fs.readFileSync(TEMPLATE_MANIFEST_PATH, "utf8");
 const TEMPLATE_MANIFEST = JSON.parse(TEMPLATE_MANIFEST_TEXT);
 const ROOT_EXCLUDED_ENTRIES = new Set(TEMPLATE_MANIFEST.excludeRootEntries);
@@ -29,60 +20,96 @@ const EXCLUDED_RELATIVE_PATHS = new Set(TEMPLATE_MANIFEST.excludePaths);
 const RENDERED_RELATIVE_PATHS = new Set(TEMPLATE_MANIFEST.renderPaths);
 const EXAMPLE_DOC_PATHS = new Set(TEMPLATE_MANIFEST.exampleDocPaths);
 const TEMPLATE_METADATA_FILENAME = ".yss-template.json";
+const PROJECT_INSTANCE_MANIFEST =
+  "schema_version: 1\nrepository_mode: project-instance\n";
 const TEMPLATE_MANIFEST_VERSION = sha256(TEMPLATE_MANIFEST_TEXT);
-const REPO_TRACKED_STATE = IS_REPO_DEVELOPMENT
-  ? loadRepoTrackedState(REPO_TEMPLATE_ROOT)
-  : null;
+const REPO_TRACKED_STATE = null;
 
 function sha256(value) {
   return crypto.createHash("sha256").update(value).digest("hex");
 }
 
-function nowIsoString() {
-  return new Date().toISOString();
+function symlinkHash(linkTarget) {
+  return sha256(`symlink:${linkTarget}`);
 }
 
-function getTemplateSource() {
-  return IS_REPO_DEVELOPMENT
-    ? "repo-development"
-    : `npm:${PACKAGE_MANIFEST.name}@${PACKAGE_MANIFEST.version}`;
+function managedPathHash(filePath) {
+  const stat = fs.lstatSync(filePath);
+  if (stat.isSymbolicLink()) {
+    return symlinkHash(fs.readlinkSync(filePath));
+  }
+  return sha256(fs.readFileSync(filePath));
 }
 
-function loadRepoTrackedState(repoRoot) {
-  const result = spawnSync("git", ["ls-files"], {
-    cwd: repoRoot,
-    encoding: "utf8",
-  });
-
-  if (result.status !== 0) {
-    return null;
+function assertSafeTemplateSymlink(relativePath, linkTarget) {
+  const resolvedRelativeTarget = path.posix.normalize(
+    path.posix.join(path.posix.dirname(relativePath), linkTarget),
+  );
+  if (
+    path.isAbsolute(linkTarget) ||
+    resolvedRelativeTarget === ".." ||
+    resolvedRelativeTarget.startsWith("../")
+  ) {
+    throw new Error(`模板包含越界符号链接：${relativePath} -> ${linkTarget}`);
   }
+}
 
-  const files = new Set();
-  const directories = new Set();
+function nowIsoString() {
+  return new Date().toISOString();
+}
 
-  for (const entry of result.stdout.split(/\r?\n/)) {
-    if (!entry) {
+function parseProjectManifest(content, label) {
+  const values = {};
+  for (const rawLine of content.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) {
       continue;
     }
 
-    const normalizedEntry = entry.split(path.sep).join("/");
-    files.add(normalizedEntry);
+    const match = line.match(/^([a-z_]+):\s*([^\s#]+)\s*$/);
+    if (!match) {
+      throw new Error(`${label}包含无法识别的内容：${rawLine}`);
+    }
+    const [, key, value] = match;
+    if (key !== "schema_version" && key !== "repository_mode") {
+      throw new Error(`${label}包含未知字段：${key}`);
+    }
+    if (Object.hasOwn(values, key)) {
+      throw new Error(`${label}包含重复字段：${key}`);
+    }
+    values[key] = value;
+  }
+
+  return values;
+}
 
-    const segments = normalizedEntry.split("/");
-    segments.pop();
+function readBundledProjectManifest() {
+  const manifestPath = path.join(TEMPLATE_ROOT, "yss-project.yaml");
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error("模板缺少 yss-project.yaml");
+  }
 
-    let current = "";
-    for (const segment of segments) {
-      current = current ? `${current}/${segment}` : segment;
-      directories.add(current);
-    }
+  const values = parseProjectManifest(
+    fs.readFileSync(manifestPath, "utf8"),
+    "模板 yss-project.yaml ",
+  );
+
+  if (values.schema_version !== "1") {
+    throw new Error(
+      `不支持的 yss-project.yaml schema_version：${values.schema_version || "缺失"}`,
+    );
+  }
+  if (values.repository_mode !== "template-source") {
+    throw new Error(
+      `模板 yss-project.yaml 的 repository_mode 必须为 template-source，实际为 ${values.repository_mode || "缺失"}`,
+    );
   }
 
-  return {
-    files,
-    directories,
-  };
+  return values;
+}
+
+function getTemplateSource() {
+  return `npm:${PACKAGE_MANIFEST.name}@${PACKAGE_MANIFEST.version}`;
 }
 
 function parseArgs(argv) {
@@ -256,6 +283,10 @@ function shouldSkipRepoDevelopmentPath(relativePath, isDirectory) {
 }
 
 function renderTemplateFile(relativePath, content, variables) {
+  if (relativePath === "yss-project.yaml") {
+    return PROJECT_INSTANCE_MANIFEST;
+  }
+
   if (relativePath === "AGENTS.md") {
     return content
       .replace(/(\*\*项目名称：\*\*\s*)\[填写\]/, `$1${variables.projectName}`)
@@ -282,13 +313,17 @@ function collectManagedFileHashes(operations) {
   const managedFiles = {};
 
   for (const operation of operations) {
-    if (operation.type !== "copy" && operation.type !== "render") {
+    if (
+      operation.type !== "copy" &&
+      operation.type !== "render" &&
+      operation.type !== "symlink"
+    ) {
       continue;
     }
 
     managedFiles[operation.relativePath] = {
       type: operation.type,
-      contentHash: sha256(fs.readFileSync(operation.targetPath)),
+      contentHash: managedPathHash(operation.targetPath),
     };
   }
 
@@ -361,6 +396,19 @@ function buildCopyPlan(sourceDir, targetDir, variables, relativeDir = "") {
       continue;
     }
 
+    if (entry.isSymbolicLink()) {
+      const linkTarget = fs.readlinkSync(sourcePath);
+      assertSafeTemplateSymlink(relativePath, linkTarget);
+      operations.push({
+        type: "symlink",
+        relativePath,
+        sourcePath,
+        targetPath,
+        linkTarget,
+      });
+      continue;
+    }
+
     if (!entry.isFile()) {
       continue;
     }
@@ -451,6 +499,13 @@ function executePlan(operations, variables) {
       continue;
     }
 
+    if (operation.type === "symlink") {
+      fs.mkdirSync(path.dirname(operation.targetPath), { recursive: true });
+      fs.rmSync(operation.targetPath, { recursive: true, force: true });
+      fs.symlinkSync(operation.linkTarget, operation.targetPath);
+      continue;
+    }
+
     fs.mkdirSync(path.dirname(operation.targetPath), { recursive: true });
     fs.copyFileSync(operation.sourcePath, operation.targetPath);
   }
@@ -482,6 +537,241 @@ function loadTemplateMetadata(targetDir) {
   };
 }
 
+function assertSupportedTargetRepositoryMode(targetDir) {
+  const manifestPath = path.join(targetDir, "yss-project.yaml");
+  if (!fs.existsSync(manifestPath)) {
+    return;
+  }
+
+  const content = fs.readFileSync(manifestPath, "utf8");
+  const values = parseProjectManifest(content, "目标 yss-project.yaml ");
+  if (values.schema_version !== "1") {
+    throw new Error(
+      `不支持的目标 yss-project.yaml schema_version：${values.schema_version || "缺失"}`,
+    );
+  }
+
+  const repositoryMode = values.repository_mode;
+  if (
+    repositoryMode !== "template-source" &&
+    repositoryMode !== "project-instance"
+  ) {
+    throw new Error(
+      `不支持的目标 yss-project.yaml repository_mode：${repositoryMode || "缺失"}`,
+    );
+  }
+}
+
+function collectFilesRecursively(rootDir, relativeDir = "") {
+  if (!fs.existsSync(rootDir)) {
+    return [];
+  }
+
+  const files = [];
+  for (const entry of fs.readdirSync(rootDir, { withFileTypes: true })) {
+    const relativePath = relativeDir
+      ? path.posix.join(relativeDir, entry.name)
+      : entry.name;
+    const absolutePath = path.join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...collectFilesRecursively(absolutePath, relativePath));
+    } else if (entry.isFile()) {
+      files.push(relativePath);
+    }
+  }
+  return files;
+}
+
+function buildLegacyMigrationPlan(targetDir) {
+  const moves = [];
+  const removeFiles = [];
+  const removeDirectories = [];
+  const conflicts = [];
+  const targetManifestPath = path.join(targetDir, "yss-project.yaml");
+  const rewriteProjectManifest =
+    fs.existsSync(targetManifestPath) &&
+    fs.readFileSync(targetManifestPath, "utf8") !== PROJECT_INSTANCE_MANIFEST;
+  const addMove = (legacyPath, nextPath) => {
+    const sourcePath = path.join(targetDir, legacyPath);
+    const targetPath = path.join(targetDir, nextPath);
+    if (!fs.existsSync(sourcePath)) {
+      return;
+    }
+    if (!fs.existsSync(targetPath)) {
+      moves.push({ legacyPath, nextPath, sourcePath, targetPath });
+      return;
+    }
+
+    const sourceHash = sha256(fs.readFileSync(sourcePath));
+    const targetHash = sha256(fs.readFileSync(targetPath));
+    if (sourceHash === targetHash) {
+      removeFiles.push({ legacyPath, sourcePath });
+    } else {
+      conflicts.push({ legacyPath, nextPath });
+    }
+  };
+
+  addMove(
+    "docs/templates/prd-template.md",
+    "docs/templates/spec-template.md",
+  );
+  addMove(
+    "docs/templates/vertical-slice-issue-template.md",
+    "docs/templates/vertical-slice-ticket-template.md",
+  );
+
+  const legacyIssuesDir = path.join(targetDir, "docs/requirements/issues");
+  for (const relativePath of collectFilesRecursively(legacyIssuesDir)) {
+    addMove(
+      path.posix.join("docs/requirements/issues", relativePath),
+      path.posix.join("docs/requirements/tickets", relativePath),
+    );
+  }
+  if (fs.existsSync(legacyIssuesDir)) {
+    removeDirectories.push("docs/requirements/issues");
+  }
+
+  const requirementsDir = path.join(targetDir, "docs/requirements");
+  if (fs.existsSync(requirementsDir)) {
+    for (const entry of fs.readdirSync(requirementsDir, { withFileTypes: true })) {
+      if (entry.isFile() && entry.name.endsWith("-prd.md")) {
+        addMove(
+          path.posix.join("docs/requirements", entry.name),
+          path.posix.join(
+            "docs/requirements",
+            entry.name.replace(/-prd\.md$/, "-spec.md"),
+          ),
+        );
+      }
+    }
+  }
+
+  for (const agentRoot of [
+    ".agents",
+    ".claude",
+    ".codex",
+    ".hermes",
+    ".pi",
+    ".trae",
+    ".codebuddy",
+    ".qoder",
+    ".qwen",
+  ]) {
+    for (const skillName of ["to-prd", "to-issues"]) {
+      const relativePath = `${agentRoot}/skills/${skillName}`;
+      if (fs.existsSync(path.join(targetDir, relativePath))) {
+        removeDirectories.push(relativePath);
+      }
+    }
+  }
+
+  return {
+    moves,
+    removeFiles,
+    removeDirectories,
+    conflicts,
+    rewriteProjectManifest,
+  };
+}
+
+function assertNoLegacyMigrationConflicts(migrationPlan) {
+  if (migrationPlan.conflicts.length === 0) {
+    return;
+  }
+
+  const details = migrationPlan.conflicts
+    .map(
+      ({ legacyPath, nextPath }) =>
+        `- ${legacyPath} -> ${nextPath}`,
+    )
+    .join("\n");
+  throw new Error(`检测到旧、新资产内容冲突，未执行任何写入：\n${details}`);
+}
+
+function updateManagedFilesForMigration(metadata, migrationPlan) {
+  const managedFiles = metadata.managedFiles || {};
+  for (const operation of migrationPlan.moves) {
+    if (managedFiles[operation.legacyPath] && !managedFiles[operation.nextPath]) {
+      managedFiles[operation.nextPath] = managedFiles[operation.legacyPath];
+    }
+    delete managedFiles[operation.legacyPath];
+  }
+  for (const operation of migrationPlan.removeFiles) {
+    delete managedFiles[operation.legacyPath];
+  }
+
+  for (const relativeDir of migrationPlan.removeDirectories) {
+    for (const relativePath of Object.keys(managedFiles)) {
+      if (
+        relativePath === relativeDir ||
+        relativePath.startsWith(`${relativeDir}/`)
+      ) {
+        delete managedFiles[relativePath];
+      }
+    }
+  }
+  if (migrationPlan.rewriteProjectManifest) {
+    managedFiles["yss-project.yaml"] = {
+      type: "render",
+      contentHash: sha256(PROJECT_INSTANCE_MANIFEST),
+    };
+  }
+  metadata.managedFiles = managedFiles;
+}
+
+function applyLegacyMigration(targetDir, metadata, migrationPlan) {
+  for (const operation of migrationPlan.moves) {
+    fs.mkdirSync(path.dirname(operation.targetPath), { recursive: true });
+    fs.renameSync(operation.sourcePath, operation.targetPath);
+  }
+
+  for (const operation of migrationPlan.removeFiles) {
+    fs.rmSync(operation.sourcePath, { force: true });
+  }
+
+  for (const relativeDir of migrationPlan.removeDirectories) {
+    fs.rmSync(path.join(targetDir, relativeDir), {
+      recursive: true,
+      force: true,
+    });
+  }
+
+  if (migrationPlan.rewriteProjectManifest) {
+    fs.writeFileSync(
+      path.join(targetDir, "yss-project.yaml"),
+      PROJECT_INSTANCE_MANIFEST,
+      "utf8",
+    );
+  }
+
+  updateManagedFilesForMigration(metadata, migrationPlan);
+}
+
+function printLegacyMigration(migrationPlan, dryRun) {
+  if (
+    migrationPlan.moves.length === 0 &&
+    migrationPlan.removeFiles.length === 0 &&
+    migrationPlan.removeDirectories.length === 0 &&
+    !migrationPlan.rewriteProjectManifest
+  ) {
+    return;
+  }
+
+  console.log(dryRun ? "旧版迁移 dry-run 预览" : "旧版迁移完成");
+  for (const operation of migrationPlan.moves) {
+    console.log(`migrate: ${operation.legacyPath} -> ${operation.nextPath}`);
+  }
+  for (const operation of migrationPlan.removeFiles) {
+    console.log(`remove-duplicate: ${operation.legacyPath}`);
+  }
+  for (const relativeDir of migrationPlan.removeDirectories) {
+    console.log(`remove-obsolete: ${relativeDir}`);
+  }
+  if (migrationPlan.rewriteProjectManifest) {
+    console.log("rewrite: yss-project.yaml -> project-instance");
+  }
+}
+
 function buildSyncVariables(metadata) {
   const variables = metadata.variables || {};
 
@@ -501,7 +791,10 @@ function buildDesiredManagedOperations(targetDir, metadata) {
   const variables = buildSyncVariables(metadata);
 
   return buildCopyPlan(TEMPLATE_ROOT, targetDir, variables).filter(
-    (operation) => operation.type === "copy" || operation.type === "render",
+    (operation) =>
+      operation.type === "copy" ||
+      operation.type === "render" ||
+      operation.type === "symlink",
   );
 }
 
@@ -522,6 +815,14 @@ function buildDesiredManagedFile(operation, metadata) {
     };
   }
 
+
+  if (operation.type === "symlink") {
+    return {
+      ...operation,
+      desiredHash: symlinkHash(operation.linkTarget),
+    };
+  }
+
   return {
     ...operation,
     desiredHash: sha256(fs.readFileSync(operation.sourcePath)),
@@ -552,7 +853,7 @@ function classifySyncPlan(targetDir, metadata) {
         continue;
       }
 
-      const currentHash = sha256(fs.readFileSync(operation.targetPath));
+      const currentHash = managedPathHash(operation.targetPath);
       if (currentHash === operation.desiredHash) {
         unchanged.push(operation);
       } else {
@@ -569,7 +870,7 @@ function classifySyncPlan(targetDir, metadata) {
       continue;
     }
 
-    const currentHash = sha256(fs.readFileSync(operation.targetPath));
+    const currentHash = managedPathHash(operation.targetPath);
     if (currentHash !== existingRecord.contentHash) {
       skipped.push({
         ...operation,
@@ -632,6 +933,12 @@ function applyManagedFileOperation(operation) {
     return;
   }
 
+  if (operation.type === "symlink") {
+    fs.rmSync(operation.targetPath, { recursive: true, force: true });
+    fs.symlinkSync(operation.linkTarget, operation.targetPath);
+    return;
+  }
+
   fs.copyFileSync(operation.sourcePath, operation.targetPath);
 }
 
@@ -653,7 +960,7 @@ function syncTemplateInstance(targetDir, metadata, dryRun) {
       continue;
     }
 
-    const currentHash = sha256(fs.readFileSync(operation.targetPath));
+    const currentHash = managedPathHash(operation.targetPath);
     if (currentHash !== operation.desiredHash) {
       continue;
     }
@@ -706,6 +1013,7 @@ function syncTemplateInstance(targetDir, metadata, dryRun) {
 }
 
 async function runInit(argv = []) {
+  readBundledProjectManifest();
   const promptedOptions = await promptForMissingOptions(parseArgs(argv));
   assertRequiredOptions(promptedOptions);
 
@@ -743,9 +1051,17 @@ async function runInit(argv = []) {
 }
 
 function runSync(argv = []) {
+  readBundledProjectManifest();
   const options = parseArgs(argv);
   const targetDir = normalizeTargetDir(options.targetDir || ".");
   const { metadata } = loadTemplateMetadata(targetDir);
+  assertSupportedTargetRepositoryMode(targetDir);
+  const migrationPlan = buildLegacyMigrationPlan(targetDir);
+  assertNoLegacyMigrationConflicts(migrationPlan);
+  if (!options.dryRun) {
+    applyLegacyMigration(targetDir, metadata, migrationPlan);
+  }
+  printLegacyMigration(migrationPlan, Boolean(options.dryRun));
   syncTemplateInstance(targetDir, metadata, Boolean(options.dryRun));
 }
 

package/template/.agents/skills/ask-matt/SKILL.md

@@ -20,16 +20,16 @@ The route most work travels. You have an idea and want it built.
    - **`/prototype`** to answer the question with throwaway code,
    - **`/handoff`** back what you learned, and reference it from the original idea thread.
 3. **Branch — is this a multi-session build?**
-   - **Yes** → **`/to-prd`** (turn the thread into a PRD) → **`/to-issues`** (split the PRD into independently-grabbable issues). Because the issues are independent, **clear context between each one**: start a fresh session per issue and kick off **`/implement`** by passing it the PRD and the single issue to work on.
+   - **Yes** → **`/to-spec`** (turn the thread into a spec), then **`/to-tickets`** to split it into tracer-bullet tickets, each declaring its **blocking edges**. On a local tracker that's one file per ticket under `.scratch/<feature>/tickets/`, worked blockers-first by hand; on a real tracker the edges become native blocking links, so any ticket whose blockers are done can be grabbed — kick off **`/implement`** per ticket, **clearing context between each one**.
    - **No** → **`/implement`** right here, in the same context window.
 
    Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`**, a two-axis review (Standards + Spec) of the diff, before committing. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point.
 
 ### Context hygiene
 
-Keep steps 1–3 in **one unbroken context window** — don't compact or clear until after `/to-issues` — so the grilling, PRD, and issues all build on the same thinking. Each `/implement` then starts fresh, working from the issue.
+Keep steps 1–3 in **one unbroken context window** — don't compact or clear until after `/to-tickets` — so the grilling, spec, and tickets all build on the same thinking. Each `/implement` then starts fresh, working from the ticket.
 
-The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~120k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-issues`, don't push on degraded — `/handoff` and continue in a fresh thread.
+The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~120k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-tickets`, don't push on degraded — `/handoff` and continue in a fresh thread.
 
 ## On-ramps
 
@@ -37,10 +37,14 @@ A starting situation that generates work, then merges onto the main flow.
 
 - **Bugs and requests piling up** → **`/triage`**. It moves issues through triage roles and produces agent-ready issues, which **`/implement`** later picks up.
 
-  Triage is only for issues **you didn't create** — bug reports, incoming feature requests, anything that arrives raw. Issues that `/to-issues` produced are already agent-ready, so **don't triage them**.
+  Triage is only for issues **you didn't create** — bug reports, incoming feature requests, anything that arrives raw. Tickets that `/to-tickets` produced are already agent-ready, so **don't triage them**.
 
 - **Something's broken** → **`/diagnosing-bugs`**. For the hard ones: the bug that resists a first glance, the intermittent flake, the regression that crept in between two known-good states. It refuses to theorise until it has a **tight feedback loop** — one command that already goes red on *this* bug — then fixes with a regression test. Its post-mortem hands off to **`/improve-codebase-architecture`** when the real finding is that there's no good seam to lock the bug down.
 
+- **A huge, foggy effort — a greenfield project or a huge feature build, too big for one session** → **`/wayfinder`**, the most cognitively demanding flow here. When the way from here to the destination isn't visible yet, it charts a **shared map** of **decision tickets** on the issue tracker and resolves them one at a time — producing **decisions, not deliverables** — until the fog is pushed back and the way is clear. Where **`/grill-with-docs`** sharpens an idea you can hold in one session, wayfinder is for the idea you can't — and it's slower and denser, so save it for exactly that, never a well-scoped feature.
+
+  When the map clears, **it hands off, it doesn't build**: merge onto the main flow at **`/to-spec`**, which collapses the map's linked decisions into a buildable plan, then `/to-tickets` and `/implement` as usual. Looping the map straight into `/implement` skips that collapse and throws the linked detail away — go straight to `/implement` only when the effort turned out genuinely small.
+
 ## Codebase health
 
 Not feature work — upkeep.

package/template/.agents/skills/ask-matt/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Ask Matt"
+  short_description: "Find the right skill or workflow"
+policy:
+  allow_implicit_invocation: false