跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

check-specs-alignment

Verify alignment between code and specs. Usage /groundwork:check-specs-alignment

etr · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add etr/groundwork --skill check-specs-alignment

技能说明


name: check-specs-alignment description: Verify alignment between code and specs. Usage /groundwork:check-specs-alignment argument-hint: "[alignment-context]" allowed-tools: ["Read", "Glob", "Grep", "Task", "Skill"]

Check Alignment Skill

Verifies that implementation aligns with product specs and architecture, surfacing misalignments for resolution.

Pre-flight: Model Recommendation

Your current effort level is {{effort_level}}.

Skip this step silently if effort is high, xhigh, or max (the scale is low < medium < high < xhigh < max, so xhigh and max are already above high) AND you are Sonnet or Opus. If effort is low or medium (i.e. below high), you MUST show the recommendation prompt — regardless of model. If you are not Sonnet or Opus, you MUST show the recommendation prompt - regardless of effort level.

Otherwise → use AskUserQuestion:

{
  "questions": [{
    "question": "Do you want to switch? Drift detection and categorization across implementation and specs benefits from consistent reasoning.\n\nTo switch: cancel, run `/effort high` (and `/model sonnet` if on Haiku), then re-invoke this skill.",
    "header": "Recommended: Sonnet or Opus at high effort",
    "options": [
      { "label": "Continue" },
      { "label": "Cancel — I'll switch first" }
    ],
    "multiSelect": false
  }]
}

If the user selects "Cancel — I'll switch first": output the switching commands above and stop. Do not proceed with the skill.

Step 0: Resolve Project Context

Before loading specs, ensure project context is resolved:

  1. Monorepo check: Does .groundwork.yml exist at the repo root?
    • If yes → Is {{project_name}} non-empty?
      • If empty → Invoke Skill(skill="groundwork:select-project") to select a project, then restart this skill.
      • If set → Project is {{project_name}}, specs at {{specs_dir}}/.
    • If no → Continue (single-project repo).
  2. CWD mismatch check (monorepo only):
    • Skip if not in monorepo mode or if the project was just selected in item 1 above.
    • If CWD is the repo root → fine, proceed.
    • Check which project's path CWD falls inside (compare against all projects in .groundwork.yml).
    • If CWD is inside the selected project's path → fine, proceed.
    • If CWD is inside a different project's path → warn via AskUserQuestion:

      "You're working from <cwd> (inside [cwd-project]), but the selected Groundwork project is [selected-project] ([selected-project-path]/). What would you like to do?"

      • "Switch to [cwd-project]"
      • "Stay with [selected-project]" If the user switches, invoke Skill(skill="groundwork:select-project").
    • If CWD doesn't match any project → proceed without warning (shared directory).
  3. Proceed with the resolved project context. All {{specs_dir}}/ paths will resolve to the correct location.

Workflow

Step 1: Load All Context

Read the following specs (each may be a single file or directory):

  • Product specs - PRD with EARS requirements

    • Single file: {{specs_dir}}/product_specs.md
    • Directory: {{specs_dir}}/product_specs/ (aggregate all .md files)
  • Architecture - Architecture decisions

    • Single file: {{specs_dir}}/architecture.md
    • Directory: {{specs_dir}}/architecture/ (aggregate all .md files)
  • Tasks - Task list (if exists)

    • Single file: {{specs_dir}}/tasks.md
    • Directory: {{specs_dir}}/tasks/ (aggregate all .md files)

Detection: Check for file first (takes precedence), then directory. When reading a directory, aggregate all .md files recursively with _index.md first, then numerically-prefixed files, then alphabetically.

Scan codebase for implementation:

  • Source files in common locations (src/, lib/, app/, etc.)
  • Configuration files
  • Database schemas/migrations
  • API definitions

If specs are missing:

"Cannot check alignment - missing specs:

  • [List missing specs]

Run the appropriate commands to create them:

  • PRD: /groundwork:design-product
  • Architecture: /groundwork:design-architecture
  • Tasks: /groundwork:create-tasks"

Step 2: Check PRD Alignment

For each EARS requirement in the PRD:

  1. Search codebase for implementation evidence using the requirement's keywords and expected behavior

  2. Categorize the implementation status:

    • Implemented - Code clearly implements the requirement
    • Partially Implemented - Some aspects present, others missing
    • Not Implemented - No evidence of implementation
    • Deviated - Implementation differs from requirement
  3. Detect undocumented features - Code functionality that doesn't trace to any PRD requirement

Step 3: Check Architecture Alignment

For each architecture decision (DR-NNN):

  1. Verify implementation follows the decision by examining:

    • Technology choices in package.json, requirements.txt, or equivalent
    • Code patterns matching the documented approach
    • Component structure matching architecture diagrams
  2. Detect deviations:

    • Different technology used than documented
    • Different patterns than documented
    • Missing components that should exist per architecture
    • Extra components not mentioned in architecture

Step 4: Report Findings

Present the alignment report in a structured format:

## Alignment Report

### PRD Alignment

| Requirement | Status | Notes |
|-------------|--------|-------|
| PRD-XXX-REQ-001 | Implemented | Found in src/auth/login.ts |
| PRD-XXX-REQ-002 | Partial | Missing error handling for edge case |
| PRD-XXX-REQ-003 | Not Implemented | - |
| PRD-YYY-REQ-001 | Deviated | Uses polling instead of WebSocket |

**Summary:** X/Y requirements implemented, Z partial, W not implemented, V deviated

**Undocumented Features:**
- Feature X in src/foo.ts has no PRD requirement
- [Or "None detected" if clean]

### Architecture Alignment

| Decision | Status | Notes |
|----------
阅读完整来源 ↗