SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsalign-work-item-manifest

align-work-item-manifest

Design & creation

View repository

Updated 10-16 06:50

About this skill

Skill: Align Work-Item Manifest

Purpose: When a project uses acentral manifest file(such as docs/process-management/now/<slug>.md) to register related artifacts, detect drift between the manifest file and the physical artifacts.

Purpose

Central-manifest-style projects maintain a manifest file (such as docs/process-management/now/<slug>.md) for each topic or Now tier entry, registering the associated requirement / design / tasks / PR. Manifests drift easily: files are added without being registered, files are deleted without being removed, or the manifest lists entries whose physical files do not exist. This skillread-onlydetects this drift and outputs an alignment report; maintenance is performed by the user or downstream tools.

v1.0.0 advisory-only: does not automatically write manifests, does not move files, does not modify frontmatter.

Core Objective

Primary objective: Accurately detect manifest-physical drift and output an actionable difference list.

Success criteria(all must be satisfied):

  1. ✅ All files in the project matching the manifest glob (default docs/process-management/now/*.md, overridable by ARTIFACT_NORMS.md) have been scanned; ifno manifest file exists, explicitly state that the project does not adopt the central manifest style, stop, and return a diagnosis
  2. ✅ For each manifest, its declared file list has been compared against the existence of physical files
  3. ✅ Three types of drift have been output:dangling references(in manifest, not in files) / unregistered(in files, not in manifest) / name mismatch(file path inconsistent with manifest declaration)
  4. ✅ No manifest or artifact has been automatically written

Acceptance test: Can the report be directly consumed by plan-next as a G3 truth drift?

Scope Boundaries

This skill is responsible for：

  • Manifest scanning and comparison against physical file existence
  • Drift classification and report output
  • Providingsuggestedremediation steps (not executed)

This skill is not responsible for：

  • Maintaining manifests(user or a future v2.x automatic maintenance mechanism)
  • Link mode identification (by discover-docs-norms）
  • Link mode selection (by define-docs-norms）
  • Actual creation / deletion / movement of downstream files

Handoff Point: After the drift report is output, the user manually corrects the manifest / files, or plan-next 's G3 routing further routes to align-planning / tidy-repo。

Use Cases

  • Periodic health checks for central-manifest-style projects
  • In-depth diagnosis when the plan-next report has G3 drift and a manifest file is detected
  • Manifest inventory before iteration wrap-up
  • Initial alignment after migrating from no manifest to the central manifest style

Behavior

Phase 0: Norms Resolution

Implemented per specs/artifact-contract.md §8 Runtime Norms Resolution Protocol 's §8.2 / §8.3 / §8.5:

  1. Read project norms → determine this skill's output work-item-manifest-alignment 's path_pattern(default docs/calibration/work-item-manifest-alignment.md）
  2. Read the manifest glob pattern from the norms (default docs/process-management/now/*.md; overridable by ARTIFACT_NORMS.md)
  3. Pre-check: If the manifest glob matches no files,Stop and output diagnosticsExplain that the project does not adopt a central manifest style
  4. This skill produces output for fixed-path governance and does not involve pattern branches outside the path

Stage 1: Manifest Scanning

  1. Glob all manifest files using the manifest location pattern obtained in Step 0
  2. For each manifest, parse the sub-artifact references listed in it (requirement / design / tasks / PR)
  3. Build the manifest declaration map:manifest → [declared_file_paths]

Stage 2: Physical Comparison

  1. For each declared_file_path check physical existence
  2. Scan the manifest-covered directories (such as requirements / designs / tasks directories) to list all actual physical files
  3. Cross-comparison:
    • Dangling reference: listed in the manifest but physically absent
    • Unregistered: physically present but not listed in any manifest
    • Name mismatch: manifest declares docs/foo/bar.md, actual file is at docs/foo/bar-v2.md(fuzzy match on the same slug)

Stage 2.5: Drift Detection Decision Branches

Branch ID Trigger Condition Determination Result Report Action
D1-no-manifest manifest glob has no matches The project does not adopt a central manifest style Stop the process, return diagnostic information, and do not write a report file
D2-declared-missing declared_file_path does not exist Dangling reference Record in the "Dangling reference" group, recommend deleting the manifest entry or creating the file
D3-physical-unregistered The physical file exists but is not declared by any manifest Unregistered Record in the "Unregistered" group, recommend appending to the manifest or archiving the file
D4-slug-mismatch The manifest path does not exist, but a candidate file with the same slug exists Name mismatch Record in the "Name mismatch" group, recommend updating the manifest path or renaming the file
D5-consistent Manifest declarations and physical files correspond one-to-one No drift Do not record an issue; only increment the "aligned items" count
D6-parse-error The manifest content cannot be parsed into declared paths Data quality anomaly (not one of the three drift types) Record in the diagnostic appendix and mark that the manifest format requires manual repair

Determination priority:D1 > D6 > D2/D4 > D3 > D5. When the same declaration simultaneously matches multiple conditions, take the first branch by priority to avoid double counting.

Stage 3: Report Production

Write to the path parsed in Stage 0 (default docs/calibration/work-item-manifest-alignment.md）：

# 工作项清单对齐报告

**日期**：<ISO>
**清单数量**：<N>
**漂移总数**：<M>（悬挂 <X> / 未登记 <Y> / 命名不符 <Z>）

## 悬挂引用（清单有，文件无）

| 清单 | 清单声明路径 | 建议 |
|---|---|---|
| ... | ... | 删除清单条目 or 创建缺失文件 |

## 未登记（文件有，清单无）

| 文件 | 疑似所属清单 | 建议 |
|---|---|---|
| ... | ... | 追加到清单 or 归档文件 |

## 命名不符（同 slug，路径异）

| 清单声明 | 物理文件 | 建议 |
|---|---|---|
| ... | ... | 更新清单路径 or 重命名文件 |

Input & Output

Input：

  • Project path (default CWD)
  • Optional manifest glob pattern (overrides the specification)
  • Optional artifact_norms_path

Output：

  • docs/calibration/work-item-manifest-alignment.md(default) or the path declared by the specification
  • Machine-readable drift summary (embedded in the report as a YAML fence) for plan-next to consume

Restrictions

Hard Boundaries

  • Read-only: v1.0.0 does not write any manifest files and does not create / delete / move any artifacts
  • When there is no physical manifest file, it must stop and provide diagnostic explanation
  • Does not identify link patterns on its own (depends on discover-docs-norms 's output)
  • Do not trigger downstream skills beyond authority (tidy-repo / align-planning by user or plan-next routing)

Skill Boundaries

Action Ownership
Pattern recognition discover-docs-norms
Pattern selection define-docs-norms
Manifest maintenance (automatic) Future v2.x or downstream skill responsibility
File archiving / renaming tidy-repo
Planning drift correction align-planning

Self-Check

  • Has read project norms per Stage 0 Norms Resolution
  • Has globbed manifest files; if no match, has stopped and diagnosed (project does not use a central manifest)
  • Has scanned all manifest files and compared against physical state
  • Has classified three types of drift (dangling / unregistered / naming mismatch)
  • Report embeds a machine-readable drift summary for plan-next consumption
  • Has not automatically modified any manifest / file

Examples

Example 1: Pure manifest project health check

Scenario: The project uses the central manifest style; there are 3 manifest files docs/process-management/now/user-auth.md / billing.md / onboarding.md。

Scan findings：

  • now/user-auth.md lists docs/designs/user-auth.md, but that file has been renamed to docs/designs/2026-04-20-user-auth.md → Naming mismatch
  • now/billing.md Manifest is complete, all files exist → no drift
  • docs/designs/onboarding-v2.md exists but now/onboarding.md is not listed → Unregistered

Output: Report 2 drift items; recommend now/user-auth.md update path,now/onboarding.md append onboarding-v2.md entry.

Example 2: Project does not adopt a central manifest (edge case)

Scenario: There is no docs/process-management/now/*.md or equivalent manifest file in the project repository.

Output: Stage 0 pre-check fails, stop and output:

未检测到任何 manifest 文件（glob: docs/process-management/now/*.md）。
本技能适用于采用中央清单文件登记制品的项目；当前项目未见此风格文件。
如需启用，可手动建清单文件（例：docs/process-management/now/user-auth.md），再重跑本技能。

Do not write a report file; return diagnostic information.

Appendix: Output Contract

This skill produces a Work Item Manifest Alignment Report (advisory only, does not write to the manifest):

Element Format Required fields Path pattern
Report body Markdown front-matter; sections: summary / three drift groups (registered_missing / unregistered_present / metadata_mismatch) / recommended manual actions docs/calibration/work-item-manifest-alignment.md
Drift item List item id / category / manifest_entry / artifact_path / evidence / proposed_action (advisory, not automatically executed) Under the three drift groups
Machine-readable block YAML fenced yaml drift_summary: counts{registered_missing,unregistered_present,metadata_mismatch}; each items[] entry contains id/category/artifact_path/proposed_action At the end of the report, for plan-next consumption