agent-project-sdlc 0.1.5 → 0.1.6

package/assets/templates/SKILL_TEMPLATE.md

@@ -15,6 +15,8 @@ description: Use when ...
 
 角色提示词应保持通用，不绑定具体业务项目；如果必须依赖项目事实，应要求读取 `.docs/`、`<harnessRoot>/state/**` 或当前 task contract，而不是写入固定业务假设。
 
+项目如果需要补充阶段角色要求，应在 `<harnessRoot>/pjsdlc_managed/override_skills/<skill_name>.md` 写追加提示词，并运行 `sdlc-harness sync` 合成最终 `SKILL.md`；不要直接修改 package-managed Skill 文件。
+
 ## 输入
 
 - `<harnessRoot>/state/lifecycle.yaml`

package/dist/lib/config.js

@@ -21,7 +21,10 @@ export function defaultConfig(root) {
             { path: harnessPath(root, "pjsdlc_managed", "make", "sdlc-harness.mk"), strategy: "managed" },
             { path: ".github/workflows/harness.yml", strategy: "create-if-missing" }
         ],
-        local_overrides: [harnessPath(root, "overrides/**"), harnessPath(root, "pjsdlc_managed", "policies", "*.local.yaml")],
+        local_overrides: [
+            harnessPath(root, "pjsdlc_managed", "override_skills", "*.md"),
+            harnessPath(root, "pjsdlc_managed", "policies", "*.local.yaml")
+        ],
         never_overwrite: [".docs/**", harnessPath(root, "state/**"), "src/**", "tests/**"]
     };
 }

package/dist/lib/migrations.js

@@ -56,6 +56,7 @@ async function migrateLegacyManagedPaths(projectRoot, root, report) {
     await moveIfDestinationMissing(projectRoot, harnessPath(root, "templates"), harnessPath(root, "pjsdlc_managed", "templates"), report);
     await moveIfDestinationMissing(projectRoot, harnessPath(root, "policies"), harnessPath(root, "pjsdlc_managed", "policies"), report);
     await moveIfDestinationMissing(projectRoot, harnessPath(root, "make"), harnessPath(root, "pjsdlc_managed", "make"), report);
+    await moveIfDestinationMissing(projectRoot, harnessPath(root, "overrides", "skills"), harnessPath(root, "pjsdlc_managed", "override_skills"), report);
 }
 async function movePromptTreeToSkillsIfDestinationMissing(projectRoot, legacyRelativePath, nextRelativePath, report) {
     const legacyPath = path.join(projectRoot, legacyRelativePath);
@@ -104,6 +105,11 @@ async function moveIfDestinationMissing(projectRoot, legacyRelativePath, nextRel
     report.changed.push(`${legacyRelativePath} -> ${nextRelativePath}`);
 }
 function migrateLocalOverride(item, root) {
+    if (item === harnessPath(root, "overrides/**") ||
+        item === harnessPath(root, "overrides", "skills", "*.md") ||
+        item === harnessPath(root, "overrides", "skills", "**")) {
+        return harnessPath(root, "pjsdlc_managed", "override_skills", "*.md");
+    }
     if (item === ".harness/policies/*.local.yaml" ||
         item === harnessPath(root, "managed", "policies", "*.local.yaml")) {
         return harnessPath(root, "pjsdlc_managed", "policies", "*.local.yaml");

package/dist/lib/sync-engine.js

@@ -30,14 +30,8 @@ async function syncManagedFile(projectRoot, root, managedFile, report) {
         await syncMakefileInclude(destination, root, report);
         return;
     }
-    if (managedFile.path === path.join(root, "skills")) {
-        await syncTree(packageAssetPath("skills"), destination, report);
-        return;
-    }
-    if (managedFile.path === path.join(root, "skills") ||
-        managedFile.path === ".harness/agents/skills" ||
-        (managedFile.path === ".agents/skills" && root !== ".agents")) {
-        await syncTree(packageAssetPath("skills"), path.join(projectRoot, root, "skills"), report);
+    if (isSkillsManagedPath(managedFile.path, root)) {
+        await syncSkillsTree(packageAssetPath("skills"), path.join(projectRoot, root, "skills"), projectRoot, root, report);
         return;
     }
     if (managedFile.path === path.join(root, "pjsdlc_managed", "templates")) {
@@ -62,6 +56,11 @@ async function syncManagedFile(projectRoot, root, managedFile, report) {
     }
     report.skipped.push(managedFile.path);
 }
+function isSkillsManagedPath(managedPath, root) {
+    return (managedPath === path.join(root, "skills") ||
+        managedPath === ".harness/agents/skills" ||
+        (managedPath === ".agents/skills" && root !== ".agents"));
+}
 async function syncAgentsBlock(destination, root, report) {
     const corePath = packageAssetPath("agents", "AGENTS_CORE.md");
     if (!(await pathExists(corePath))) {
@@ -197,6 +196,93 @@ async function syncTree(source, destination, report) {
     const changed = await copyTree(source, destination, { skipGitkeep: true });
     report.changed.push(...changed);
 }
+async function syncSkillsTree(source, destination, projectRoot, root, report) {
+    if (!(await pathExists(source))) {
+        report.skipped.push(path.basename(destination));
+        return;
+    }
+    const files = await listFiles(source);
+    const realFiles = files.filter((file) => !file.endsWith(".gitkeep"));
+    if (realFiles.length === 0) {
+        report.skipped.push(path.basename(destination));
+        return;
+    }
+    const knownSkills = new Set();
+    for (const file of realFiles) {
+        const skillName = skillNameForSourceFile(source, file);
+        if (skillName) {
+            knownSkills.add(skillName);
+        }
+    }
+    const blockedBefore = report.blocked.length;
+    const overrides = await readSkillOverrides(projectRoot, root, knownSkills, report);
+    if (report.blocked.length > blockedBefore) {
+        return;
+    }
+    for (const file of realFiles) {
+        const relative = path.relative(source, file);
+        const destinationFile = path.join(destination, relative);
+        const skillName = skillNameForSourceFile(source, file);
+        const baseContent = await readText(file);
+        const content = skillName ? renderSkillWithOverride(baseContent, overrides.get(skillName)) : baseContent;
+        if (await writeTextIfChanged(destinationFile, content)) {
+            report.changed.push(destinationFile);
+        }
+        else {
+            report.skipped.push(destinationFile);
+        }
+    }
+}
+async function readSkillOverrides(projectRoot, root, knownSkills, report) {
+    const overrides = new Map();
+    const overrideRoot = skillOverrideRoot(projectRoot, root);
+    if (!(await pathExists(overrideRoot))) {
+        return overrides;
+    }
+    for (const file of await listFiles(overrideRoot)) {
+        if (path.basename(file) === ".gitkeep") {
+            continue;
+        }
+        const relativePath = path.relative(overrideRoot, file).split(path.sep).join("/");
+        const match = relativePath.match(/^([^/]+)\.md$/);
+        if (!match || !knownSkills.has(match[1])) {
+            report.blocked.push(`unknown skill override: ${path.join(root, "pjsdlc_managed", "override_skills", relativePath)}`);
+            continue;
+        }
+        const content = await readText(file);
+        if (content.trim()) {
+            overrides.set(match[1], {
+                relativePath: path.join(root, "pjsdlc_managed", "override_skills", relativePath),
+                content
+            });
+        }
+    }
+    return overrides;
+}
+function skillOverrideRoot(projectRoot, root) {
+    return path.join(projectRoot, root, "pjsdlc_managed", "override_skills");
+}
+function skillNameForSourceFile(sourceRoot, file) {
+    const relative = path.relative(sourceRoot, file).split(path.sep).join("/");
+    const match = relative.match(/^([^/]+)\/SKILL\.md$/);
+    return match?.[1];
+}
+function renderSkillWithOverride(baseContent, override) {
+    if (!override) {
+        return baseContent;
+    }
+    const header = [
+        "",
+        "",
+        "## Local Override",
+        "",
+        `Source: \`${override.relativePath.split(path.sep).join("/")}\``,
+        "",
+        "The following project-local instructions are appended by `sdlc-harness sync`. Keep package-managed Skill files unchanged; edit the override source instead.",
+        ""
+    ].join("\n");
+    return `${baseContent.trimEnd()}${header}${override.content.trim()}\n`;
+}
 async function syncFile(source, destination, report, missingMode) {
     if (!(await pathExists(source))) {
         if (missingMode === "block-if-missing") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-project-sdlc",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "CLI and canonical assets for the AI SDLC Harness workflow.",
   "type": "module",
   "bin": {