agent-project-sdlc 0.1.5 → 0.1.7

package/README.md

@@ -0,0 +1,76 @@
+# AI SDLC Harness
+
+`agent-project-sdlc` provides the `sdlc-harness` CLI and canonical workflow assets for AI-assisted software delivery. It materializes an agent-readable lifecycle, workflow skills, templates, policies, gates and documentation structure into a project workspace.
+
+## Install
+
+```sh
+npm install -D agent-project-sdlc
+npx sdlc-harness init
+```
+
+For existing projects:
+
+```sh
+npx sdlc-harness init --adopt
+```
+
+## Capabilities
+
+| Capability | Entry Point | Description |
+|---|---|---|
+| Project initialization | `npx sdlc-harness init` | Creates `AGENTS.md`, `<harnessRoot>/state/**`, workflow skills, managed templates/policies, `.docs/**` and a Makefile include. |
+| Existing project adoption | `npx sdlc-harness init --adopt` | Adds Harness non-destructively to an existing repository. |
+| Configurable Harness root | `--harness-folder`, `package.json#sdlcHarness.harnessFolderName`, `sdlc-harness.config.json` | Supports Codex `.codex`, Claude `.claude`, Cursor `.cursor`, Cline `.cline`, Roo `.roo`, Gemini `.gemini` or a custom folder. |
+| Managed file sync | `npx sdlc-harness sync` | Materializes package canonical assets into the configured Harness root while preserving project state, docs and local overrides. |
+| Upgrade | `npx sdlc-harness upgrade` | Runs migrations and sync for already-adopted projects. |
+| Diagnostics | `npx sdlc-harness doctor` | Reports Harness root, package version, schema version and key managed paths. |
+| Validators | `npx sdlc-harness validate-*`, `make validate-current`, `make validate-harness` | Checks phase deliverables, active plan shape, prompt language contract and generated overview freshness. |
+| Lifecycle workflow | `<harnessRoot>/state/lifecycle.yaml`, `<harnessRoot>/state/plan.yaml`, `.docs/**` | Tracks REQUIREMENT_GATHERING, ARCHITECTING, SPRINTING, REVIEWING, TESTING, RELEASING and RFC_RECALIBRATION facts. |
+| Natural-language control | `AGENTS.md` plus workflow skills | Lets users say things like "continue", "start development", "run tests" or "requirements changed"; agents map these to workflow actions. |
+| Workflow skills | `<harnessRoot>/skills/pjsdlc_*/SKILL.md` | Provides role prompts for product, architecture, development, implementation docs, review, testing, release and RFC recalibration. |
+| Project-local skill overrides | `<harnessRoot>/pjsdlc_managed/override_skills/<skill_name>.md` + `npx sdlc-harness sync` | Appends project-specific role instructions to generated Skill output without editing managed Skill files. |
+| Local policy overrides | `<harnessRoot>/pjsdlc_managed/policies/*.local.yaml` | Preserves project-specific policy additions separately from package defaults. |
+| Documentation overview | `make docs-overview`, `make validate-doc-overviews` | Regenerates human-readable stage overviews from `.docs/**` fact slices. |
+| Package source checks | `sdlc-harness package sync-source`, `sdlc-harness package check-source` | Maintainer commands for keeping package canonical assets aligned with this source workspace. |
+
+## Skill Overrides
+
+Do not edit generated files under `<harnessRoot>/skills/**/SKILL.md`; `sync` and `upgrade` regenerate them.
+
+To customize a stage role prompt, create:
+
+```txt
+<harnessRoot>/pjsdlc_managed/override_skills/<skill_name>.md
+```
+
+Example:
+
+```txt
+.codex/pjsdlc_managed/override_skills/pjsdlc_dev_sprint.md
+```
+
+Then run:
+
+```sh
+npx sdlc-harness sync
+```
+
+The sync output is the package base Skill plus one appended `Local Override` block. Unknown skill names block sync so misspellings do not silently fail.
+
+## Common Commands
+
+```sh
+npx sdlc-harness init
+npx sdlc-harness init --adopt
+npx sdlc-harness sync
+npx sdlc-harness upgrade
+npx sdlc-harness doctor
+make validate-current
+make validate-harness
+make docs-overview
+```
+
+## More Information
+
+The source repository keeps the full product and architecture specification in `PROJECT_SPEC.md`, with implementation and release evidence under `.docs/**`.

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,12 +1,13 @@
 {
   "name": "agent-project-sdlc",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "CLI and canonical assets for the AI SDLC Harness workflow.",
   "type": "module",
   "bin": {
     "sdlc-harness": "dist/cli.js"
   },
   "files": [
+    "README.md",
     "dist",
     "assets",
     "migrations",