# Check Specs Alignment

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

- **Type:** Skill
- **Install:** `agentstack add skill-etr-groundwork-check-specs-alignment`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [etr](https://agentstack.voostack.com/s/etr)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [etr](https://github.com/etr)
- **Source:** https://github.com/etr/groundwork/tree/main/skills/check-specs-alignment

## Install

```sh
agentstack add skill-etr-groundwork-check-specs-alignment
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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`  "You're working from `` (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:

```markdown
## 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 |
|----------|--------|-------|
| DR-001 | Aligned | PostgreSQL used as documented |
| DR-002 | Deviated | Using REST instead of GraphQL |
| DR-003 | Aligned | - |

**Summary:** X/Y decisions aligned, Z deviated

**Undocumented Components:**
- src/cache/ not mentioned in architecture
- [Or "None detected" if clean]

### Task Status Consistency

| Condition | Count | Tasks |
|-----------|-------|-------|
| Marked complete but code missing | N | TASK-003, TASK-007 |
| Code present but task not complete | N | TASK-005 |
```

### Step 5: Suggest Resolution

Based on findings, provide actionable next steps:

**For undocumented features:**
> "Run `/groundwork:design-product` to add requirements for undocumented feature X"

**For PRD deviations:**
> "Either:
> - Run `/groundwork:source-product-specs-from-code` to update the PRD to match implementation, OR
> - Fix the implementation to match PRD requirement PRD-XXX-REQ-NNN"

**For architecture deviations:**
> "Either:
> - Run `/groundwork:source-architecture-from-code` to update architecture to match implementation, OR
> - Refactor code to follow DR-NNN (currently using [actual] instead of [documented])"

**For missing implementations:**
> "Run `/groundwork:work-on-next-task` to implement missing requirements, or `/groundwork:work-on N` to work on specific tasks"

**Offer resolution options:**
> "Found [N] misalignments. Would you like me to:
> 1. Update specs to match implementation (`/groundwork:source-product-specs-from-code`, `/groundwork:source-architecture-from-code`)
> 2. List implementation changes needed to match specs
> 3. Go through each misalignment individually"

## Categories of Misalignment

### PRD Alignment Status

| Status | Meaning | Resolution |
|--------|---------|------------|
| **Implemented** | Code matches requirement | None needed |
| **Partial** | Some aspects implemented | Complete implementation or update PRD scope |
| **Not Implemented** | No code for requirement | Implement via tasks or remove from PRD |
| **Deviated** | Different from spec | Align code OR update PRD |

### Architecture Alignment Status

| Status | Meaning | Resolution |
|--------|---------|------------|
| **Aligned** | Implementation follows decision | None needed |
| **Deviated** | Different approach used | Refactor OR update architecture |

## Search Patterns

When searching for implementation evidence:

### Requirement Keywords
- Extract verbs: "shall create", "shall display", "shall validate"
- Extract nouns: user, order, payment, notification
- Search for related function/class names

### Architecture Patterns
- Check imports/dependencies for technology choices
- Look for documented component names
- Verify directory structure matches architecture

### Common Locations
```
src/           - Main source code
lib/           - Libraries
app/           - Application code (Next.js, Rails, etc.)
api/           - API routes
components/    - UI components
services/      - Service layer
models/        - Data models
database/      - Migrations, schemas
config/        - Configuration
tests/         - Test files (can verify expected behavior)
```

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [etr](https://github.com/etr)
- **Source:** [etr/groundwork](https://github.com/etr/groundwork)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-etr-groundwork-check-specs-alignment
- Seller: https://agentstack.voostack.com/s/etr
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.