Definitions

What counts as Specification

Specification is any document that describes what should exist and how it should behave:

• Docs under spec/ and spec/feature/ directories
• README.md files at each component directory and at the repository root
• CLAUDE.md at the repository root
• Declarations in SKILL.md files (YAML frontmatter + description/routing sections at the top — everything above the detailed workflow instructions)

What counts as Implementation

Implementation is the actual code, scripts, and configs that do things:

• .prauto/ scripts, libraries, prompts, and config files
• dev_env/ scripts, manifests, and helpers
• helm-charts/ chart definitions, values, and templates
• api/ OpenAPI spec (openapi.yaml)
• src/ application code (api, backend, frontend) and tests/ directories
• Detailed logic in SKILL.md files (the workflow instruction body — everything below the declarations)
• ref/ system (reference materials and setup scripts)

The boundary inside SKILL.md

A single SKILL.md file straddles both sides:

Routing & Scope Definitions

Parse $ARGUMENTS to determine the change scope. If no arguments are given or the scope is unclear, output the following scope menu and wait for the user to reply with their selection:

Select scopes to sync (comma-separated numbers or keywords):

  1. all          — All scopes that have both spec and impl files
  2. prauto       — .prauto scripts, prauto-related specs and skills
  3. ai-scaffold  — CLAUDE.md, .claude/ settings, hooks, agents, all skills
  4. dev-env      — dev_env/ scripts, DEV_ENV spec
  5. helm-charts  — Helm chart definitions and specs
  6. api          — API specs, OpenAPI, src/api/ code
  7. ref          — ref/ setup scripts and reference materials
  8. backend      — Backend services, Temporal workflows (TBD)
  9. frontend     — Next.js frontend code (TBD)

Example: "1" or "prauto, api" or "2,3,6"

Parse the user's reply into individual scope keywords. Accept numbers, keywords, or a mix.

The directories below are starting points — always glob the actual tree to discover what exists. If files have moved or been renamed, follow the real structure rather than these hints.

• If the user selects all, expand to every scope that has both spec and impl files present.
• For scopes marked TBD: inform the user that the mapping is not yet defined and skip with a note.

Step 1 — Collect inventory

For each selected scope:

1. Glob for all spec-side and impl-side files using the areas in §Routing & Scope Definitions.
2. Build a file inventory: {scope, side, path, exists}.
3. If a scope has no spec files or no impl files, report it and skip with a warning.

Step 2 — Read and compare

For each scope, read files on both sides and identify discrepancies.

What to look for

Reading strategy

• Spec side: Read fully — these define the intended behavior.
• Impl side: Focus on structure, exported functions/endpoints, CLI options, and high-level flow. Don't read every line of business logic unless the spec describes that level of detail.
• SKILL.md: Read the declaration (frontmatter + routing) as spec; skim the logic body for workflow steps and behavioral contracts; compare the two sides against each other.

Step 3 — Classify and prioritize changes

High-level spec rules (spec hierarchy awareness)

Follow the spec hierarchy from CLAUDE.md. Higher-priority documents constrain lower ones.

Brevity rules

• CLAUDE.md (root): Keep as brief as possible. Orientation document, not a reference. Only names, key commands, and pointers to detailed specs. Remove anything that belongs in AI_SCAFFOLD.md or feature specs.
• README.md files: Quick-start focused. Prerequisites, install command, access details, link to spec. No architecture discussion.
• SKILL.md declarations: description should be one sentence. argument-hint should match actual accepted arguments.
• High-level specs (priority 1–3): Describe what and why, not how. Implementation details belong in priority 4–6 documents or in impl files.
• Generally, all spec-side documents should stay brief. They exist to orient and constrain, not to replicate implementation details.
• In spec, focus on architecture, decisions, and constraints. From spec, remove verbatim template code, full code blocks, and script snippets that duplicate the impl files.

Change direction heuristic

• If impl is more recent (has features/options that spec doesn't mention) → propose updating spec to document the current state.
• If spec has requirements that impl doesn't fulfill → flag as "spec gap in implementation" — do not auto-modify impl code (too risky without tests). Report it for the user to decide.
• If both have drifted → propose spec update to match impl reality, and list impl gaps separately.

Step 4 — Present findings and apply changes

Report format

Present a structured summary before making changes:

## Sync Report — <scope(s)>

### Discrepancies Found

#### <Scope Name>

| # | File | Side | Issue | Proposed Action |
|---|------|------|-------|-----------------|
| 1 | spec/AI_PRAUTO.md | spec | Missing reference to new lib module | Add to file tree |
| 2 | .prauto/README.md | spec | Stale prerequisites list | Update to match reality |
| 3 | .claude/skills/dev-env/SKILL.md | spec (decl) | argument-hint missing new action | Update frontmatter |
| ... | ... | ... | ... | ... |

#### Spec Gaps in Implementation (not auto-fixed)
- spec/feature/API.md requires endpoint X, but src/api/routers/ doesn't implement it

### High-Level Spec Impact
- CLAUDE.md: <no change needed | brief update proposed>
- ARCHITECTURE.md: <no change needed | update proposed>

Apply changes

1. Ask the user to confirm before applying. Show the proposed edits clearly.
2. Apply edits using the Edit tool (prefer surgical edits over full rewrites).
3. For high-level specs and CLAUDE.md, show the diff preview first — these files affect all agents.
4. After applying, re-read modified files to verify consistency.

Cross-scope consistency check

When all is selected (or multiple scopes), perform an additional pass after the per-scope steps above:

• Flag any contradictions between priority levels (e.g., a feature spec contradicting ARCHITECTURE.md, or a skill declaration contradicting its parent spec).
• The spec hierarchy in §Step 3 determines which document is authoritative when there is a conflict — higher priority wins.