anchors

name	anchors
description	Requirements-driven development framework. Use when setting up product/engineering requirements documents, checking traceability between requirements and code, verifying document consistency, or working on code in a repo that contains ANCHORS.md files (load the skill to understand the requirements context before making changes).

anchors

A skill for managing ANCHORS requirements-driven development documents.

ANCHORS keeps product requirements, engineering requirements, testing strategy, dependency constraints, and implementation in a consistent, traceable hierarchy.

---

The ANCHORS Framework

Documents

A module's ANCHORS document set consists of up to four documents plus a marker file:

Document	Purpose	Requirement IDs
ANCHORS.md	Module marker. YAML frontmatter with prefix field.	—
PRODUCT.md	Product requirements — observable behavior, outcomes, and qualities. No implementation approach. Litmus test: could you verify this requirement without reading source code? Source of truth.	P-*
ENGINEERING.md	Engineering architecture — rules, principles, and constraints that govern how the system is built. Organized by cross-cutting concern. Must not contradict PRODUCT.md.	E-*
TESTING.md	Testing strategy — pyramid, coverage invariants, tooling. Defines how requirements are verified.	—
DEPENDENCIES.md	External dependencies — what the environment must provide because the system cannot supply it.	D-DEP-*

All four documents are part of the framework. TESTING.md and DEPENDENCIES.md participate in the truth hierarchy and have defined disagreement rules.

Modes

ANCHORS operates in one of two modes:

• Embedded (default): Docs live alongside the code they describe. Requirement IDs are tagged inline in source code and tests. Check searches the local codebase for traceability. This is the standard mode.
• Detached: Docs live separately from the code they describe. The target codebase is never modified. Traceability uses → forward references in ENGINEERING.md pointing to code locations in the target codebase. Detached mode works whether the docs are in the same repo (in-repo detached) or in a completely separate repo (external detached).

Mode is set explicitly: if ANCHORS.md frontmatter contains mode: detached, the module is detached. Otherwise it's embedded.

ANCHORS.md frontmatter — embedded mode:

---
prefix: AUTH
---

ANCHORS.md frontmatter — detached mode (in-repo):

---
prefix: PENPAL
mode: detached
path: ..
---

ANCHORS.md frontmatter — detached mode (external repo):

---
prefix: AUTH
mode: detached
repo: github.com/org/auth-service
ref: main
path: src/auth
---

• mode — detached or omitted. When detached, the target code is never modified and ENGINEERING.md uses → forward references instead of inline code tags.
• repo — target codebase (GitHub URL or local path). Only used in detached mode when the code is in a different repo. Omit for in-repo detached.
• ref — branch, tag, or SHA to track (defaults to main). Only meaningful with repo.
• path — subdirectory to scope research and traceability. In-repo detached (no repo): relative to the ANCHORS.md file, like embedded mode. External detached (with repo): relative to the target repo root. Defaults to . (in-repo) or / (external).

Truth Hierarchy

PRODUCT.md (what to build — authoritative on behavior)
ENGINEERING.md (how to build it — authoritative on architecture, must not contradict PRD)
    ↓ constrains
DEPENDENCIES.md (external prerequisites — what the environment must provide)

TESTING.md (testing strategy — covers both PRODUCT.md and ENGINEERING.md)
    ↓ executed as
Tests (executable specification — truthier than implementation)
    ↓ validated against
Implementation (must satisfy all of the above)

Disagreement Rules

• Implementation vs tests → implementation is probably wrong
• Tests vs PRD/Engineering → tests are wrong (fix the tests, or update the documents first if the requirement changed)
• TESTING.md vs PRD/Engineering → TESTING.md is wrong (update the testing strategy to match the requirements)
• ENGINEERING.md vs PRD → ENGINEERING.md is wrong (PRD is authoritative)
• DEPENDENCIES.md vs ENGINEERING.md → check which is correct (ENGINEERING.md may include requirements for the system to manage something that DEPENDENCIES.md lists as external — resolve which is current)

Rules

1. PRODUCT.md is authoritative. If there is a conflict between documents, PRODUCT.md wins.
2. ENGINEERING.md must fully satisfy PRODUCT.md. Every product requirement should have corresponding engineering requirements that cover it.
3. All implementation must meet both PRD and Engineering requirements. Do not implement against only one document.
4. Keep documents consistent. When changing a requirement, update PRODUCT.md first, then ENGINEERING.md to reflect it (and link back).
5. Do not add requirements to ENGINEERING.md that contradict or extend PRODUCT.md without updating PRODUCT.md first. The PRD drives ENGINEERING.md, not the other way around.
6. Tests are truthier than implementation, but documents are truthier than tests. If the implementation diverges from the tests, the implementation is assumed buggy. If the tests diverge from the PRD or ENGINEERING.md, the tests are wrong. Fix the code to match the tests; fix the tests to match the documents; update the documents first if the requirement has genuinely changed.
7. Every P-* and E-* requirement must have test coverage. See TESTING.md for coverage invariants. A requirement without a corresponding test is a coverage gap that must be addressed.

Content Guidelines

The litmus test: a product manager should read PRODUCT.md without needing to Google anything, and a staff engineer should read ENGINEERING.md and find architectural rules that constrain real decisions — not a rephrasing of the product requirements or a step-by-step implementation spec.

PRODUCT.md — describe what users see and do:

• Name the experience, not the mechanism. "Updates in real-time" not "updates via SSE." "Interactive diagrams" not "interactive SVGs."
• Every requirement needs a visible verb — what a human sees or does. "The UI shows X", "Users can Y", "A modal appears with Z." If you can't describe an observable behavior, it belongs in ENGINEERING.md or is underspecified.
• Specify concrete details when they ARE the product requirement. "Cmd+T opens a new tab, Cmd+W closes the current tab" — not "keyboard shortcuts for tab management."
• Don't reference undefined terms. If a concept isn't self-evident from the user's perspective, define it or point to where it's defined.

ENGINEERING.md — define architectural rules and principles:

• Each entry states a cross-cutting rule, explains WHY it exists, and links to all product requirements it governs.
• Organize by architectural concern (data integrity, trust boundaries, performance invariants, extensibility), not by feature area.
• Rules should be durable — they survive refactors. Implementation details that change with each sprint belong in code comments, not here.
• A good engineering rule constrains many decisions. A bad one describes one function.
• Add WHY, don't restate WHAT. If an entry reads like a rephrasing of the P-* it links to, it's not adding value.

Document Structure

Each document follows a canonical structure. Setup generates documents matching this structure. Check validates documents against it — unrecognized sections are flagged as structural drift.

This is the self-cleaning mechanism: when the skill spec changes (e.g., a section is removed or renamed), upgrading the skill updates the canonical structure, the next check flags the now-unrecognized section, and the next setup overwrite regenerates the document to match.

All documents share:

• YAML frontmatter with scope and see-also fields
• A title heading: # {ModuleName}: {Document Type}

PRODUCT.md — flexible structure:

• ## Overview (optional) — brief product context
• ## {Functional Area} — one per area, containing P-* requirements
• ## Open Questions / ## Resolved Questions (optional)

Check validates content patterns (proper P-* IDs, anchor format) rather than specific section names, since sections are project-specific.

ENGINEERING.md — flexible structure:

• ## {Architectural Concern} — sections organized by cross-cutting concern, containing E-* requirements with ← backlinks
• ## Open Questions / ## Resolved Questions (optional)

Check validates content patterns (proper E-* IDs, backlinks) rather than specific section names.

TESTING.md — prescribed structure (H2 sections, in order):

1. ## Source of Truth Hierarchy (optional) — testable components and their truth relationships
2. ## How We Test — overview of the testing approach and what can/cannot be tested automatically
3. ## Coverage Invariants — project-specific instantiation of the 6 universal coverage invariants
4. ## Pyramid Shape — test pyramid visualization showing layer distribution
5. ## Layer {N}: {Name} — one section per test layer, detailing what each layer covers
6. ## Test Infrastructure — test runner, assertion helpers, fixtures, directory layout
7. ## Tooling — tools table (tool → purpose)
8. ## Coverage Targets — targets table (layer → target → rationale)
9. ## What We Deliberately Don't Test — explicit exclusions with rationale

Any H2 section not in this list is structural drift and should be flagged by check.

DEPENDENCIES.md — prescribed structure:

• ### D-DEP-{ID}: {Name} — one entry per dependency, with Used by, Where it runs, Why external fields

Requirement ID Conventions

PRODUCT.md — P- prefix with section-scoped slugs:

- <a id="P-AUTH-LOGIN"></a>**P-AUTH-LOGIN**: Users can log in with email and password.

ENGINEERING.md — E- prefix with backlink to the product requirements it governs:

- <a id="E-AUTH-SESSION"></a>**E-AUTH-SESSION**: Sessions use signed JWTs with 24-hour expiry.
  ← [P-AUTH-LOGIN](PRODUCT.md#P-AUTH-LOGIN)

Every E-* requirement must have a ← backlink. This is how the check tracks coverage.

ENGINEERING.md (detached mode) — E- prefix with backlink and → forward references to code locations in the target repo:

- <a id="E-AUTH-SESSION"></a>**E-AUTH-SESSION**: Sessions use signed JWTs with 24-hour expiry.
  ← [P-AUTH-LOGIN](PRODUCT.md#P-AUTH-LOGIN)
  → `src/auth/session.go:NewSession`, `src/auth/middleware.go:ValidateToken`

The → line lists file:symbol pairs wrapped in backticks, comma-separated. File paths are relative to the resolved target directory (the path directory, however it was resolved — see Modes section). Forward references replace inline code tags — in detached mode, the target code is never modified.

DEPENDENCIES.md — D-DEP- prefix:

### D-DEP-POSTGRES: PostgreSQL
- **Used by:** API server
- **Where it runs:** All environments
- **Why external:** Stateful service, cannot be bundled

Coverage Invariants

TESTING.md defines the project-specific test strategy. These invariants apply universally:

1. Every requirement has a test. Every P-* and E-* must be covered by at least one test.
2. Contract boundaries are tested from both sides. Parsers (reading) and builders (writing) are both tested.
3. Trust boundaries are tested end-to-end. Human-approval vs. automatic actions each need an E2E test.
4. Every public API surface has a test. Happy path and error path.
5. Recovery paths are tested. At integration layer or above.
6. Every interface has its production implementation verified. Test doubles don't mask missing real implementations.

Code Traceability

Tag functions and tests with requirement IDs. Augment comments, never replace them.

// BuildStartCommand builds the argument list for starting the process.
// E-CLI-START: construct CLI start invocation with config flags.
func BuildStartCommand(req StartRequest) []string {

// TestSessionExpiry verifies that expired sessions are rejected.
// E-AUTH-SESSION: sessions expire after the configured TTL.
func TestSessionExpiry(t *testing.T) {

Rules:

• One tag per function, not per line
• Keep existing descriptive comments — the tag is an addition
• Natural prose is fine: // Per E-AUTH-SESSION, tokens expire after 24 hours
• Skip self-explanatory code, boilerplate, and standard library calls
• Tag test functions too — every test file that verifies a requirement must carry the relevant E-/P- ID

Monorepo Support

ANCHORS supports arbitrary module nesting. A directory is an ANCHORS module if it contains an ANCHORS.md file with a prefix frontmatter field:

---
prefix: PAY-CHECKOUT
---

Prefixes must be unique across the repo. Within a module, PRODUCT.md/ENGINEERING.md links are relative (backlinks in ENGINEERING.md point to PRODUCT.md). Cross-module references use relative paths:

← [P-PAY-CHECKOUT-CART](../checkout/PRODUCT.md#P-PAY-CHECKOUT-CART)

Not every module needs all four documents. Pure infrastructure modules might have only ENGINEERING.md tracing to another module's PRODUCT.md. TESTING.md can be per-module or shared.

---

Routing

This skill is invoked as /anchors with optional arguments.

Parse the args to determine the mode:

User types	Mode
/anchors (no args)	Interactive — use AskUserQuestion to ask "Setup or check?" (see below)
/anchors setup	Setup — determine target path (see below)
/anchors setup path/to/dir	Setup — use the given path
/anchors check	Check
/anchors embed	Embed — convert detached module to embedded (see below)
/anchors embed path/to/dir	Embed — convert the detached module at the given path

Any other args → tell the user the available modes (setup, check, embed).

Interactive mode prompt: When invoked with no args, first check whether any ANCHORS.md files exist in the repo (glob for **/ANCHORS.md excluding node_modules, vendor, .git, build output). Then use AskUserQuestion:

• Question: "What would you like to do?"
• Header: "Mode"
• If ANCHORS modules already exist, present Check first (recommended):
  • Check — "Check traceability and consistency across modules (Recommended)"
  • Setup — "Scaffold ANCHORS documents in a new directory"
  • Embed — "Convert a detached module to embedded mode" (only show if any module has mode: detached)
• If no ANCHORS modules exist, present Setup first (recommended):
  • Setup — "Scaffold ANCHORS documents in a directory (Recommended)"
  • Check — "Check traceability and consistency across modules"

---

Setup Mode

Set up a complete ANCHORS document set for a project or module. Setup produces fully populated documents — real requirements, real engineering specs, a real testing strategy — not empty templates. A full setup (not "Skip existing") should produce a document set that passes an immediate check.

The anchors CLI handles distribution (install, upgrade) and CI (check in pipelines). The skill handles all interactive work directly — no CLI dependency at runtime.

Determine the target path

1. If a path was given as an argument, use it.
2. If no path was given, check whether the current working directory already has an ANCHORS.md.
   • No → use the current working directory.
   • Yes → use AskUserQuestion to ask for a path:
     • Question: "This directory already has ANCHORS.md. Where should the new module be set up?"
     • Header: "Path"
     • Options: suggest 2-3 likely subdirectories based on the repo structure (e.g., src/, services/, packages/). The user can always pick "Other" to type a custom path.

Steps

1. Check if any ANCHORS documents already exist in the target directory (ANCHORS.md, PRODUCT.md, ENGINEERING.md, TESTING.md, DEPENDENCIES.md; also check for legacy ERD.md). If any exist, use AskUserQuestion to confirm:

   • Question: "These ANCHORS documents already exist: [list]. Overwrite them?"
   • Header: "Overwrite"
   • Options: Skip existing ("Only create missing documents"), Overwrite all ("Replace all documents with fresh content")

2. Use AskUserQuestion to ask the user for project details (both in a single call):

   • Question 1: "What is the project/module name?" — Header: "Name" — Options: offer the target directory name as the recommended default, plus 1-2 alternatives derived from parent directories or repo name.
   • Question 2: "What requirement ID prefix should be used?" — Header: "Prefix" — Options: offer an uppercase abbreviation of the name as the recommended default, plus 1-2 alternatives (e.g., shorter/longer forms).

3. Determine the mode. Check whether the target directory contains code (source files, not just docs). If it does, this is an embedded setup — skip to step 4. If the target directory has no code (it's a standalone docs repo or empty directory), use AskUserQuestion:

   • Question: "Does this describe an existing codebase?"
   • Header: "Mode"
   • Options:
     • In-repo detached ("Yes — code is elsewhere in this repo")
     • External detached ("Yes — code is in another repo")
     • Greenfield ("No — this is a new project without existing code")

   If In-repo detached, use AskUserQuestion to collect the code location:

   • Question: "Where is the code relative to this directory?" — Header: "Path" — Suggest likely relative paths based on sibling/parent directories (e.g., .., ../../src). The user can type a custom path.

   If External detached, use AskUserQuestion to collect target repo details:

   • Question 1: "What is the target repo?" — Header: "Repo" — Free text (GitHub URL or local path)
   • Question 2: "What branch/tag/SHA to track?" — Header: "Ref" — Options: (default), , Other

---

Check Mode

Check traceability and consistency across all ANCHORS modules in the repo. Check has two layers: structural validation (deterministic) and semantic analysis (LLM-powered).

Step 1: Structural checks

Perform these checks directly:

1. Module discovery: Glob for **/ANCHORS.md (excluding node_modules, vendor, .git, build output). Read each to extract prefix from frontmatter.
2. Prefix uniqueness: Verify no two modules share a prefix.
3. Document presence: For each module, check which of PRODUCT.md, ENGINEERING.md, TESTING.md, DEPENDENCIES.md exist.
4. Engineering backlinks: For each E-* ID anchor in ENGINEERING.md (id="E-..."), verify a ← [P-* backlink appears within the next 5 lines.
5. PRD coverage: For each P-* ID anchor in PRODUCT.md, verify it appears somewhere in ENGINEERING.md.
6. Forward references (detached only): For each → line in ENGINEERING.md, extract `file:symbol` pairs and verify the file exists and contains the symbol in the resolved target directory.
7. Open questions: Scan all docs for unresolved **OPEN-** patterns (skip struck-through and backtick-quoted).

Structural errors are definitive — report them directly.

Step 2: Semantic analysis (skill-only)

After the structural check, the skill performs deeper analysis that requires understanding the code and requirements:

1. For detached modules, resolve the target codebase. For each detached module: In-repo (no repo field): resolve path relative to the ANCHORS.md file. External (with repo): access the codebase at repo and ref, scoped to path (defaulting to /). Cache or reuse the resolved target for subsequent steps.

2. Check document structure. Validate each document against the canonical structure defined in the Document Structure section. For TESTING.md, verify all required H2 sections are present and flag any H2 sections not in the canonical list as structural drift. For PRODUCT.md and ENGINEERING.md, verify sections contain properly formatted requirements (P-*/E-* IDs, backlinks). Report structural drift in the gaps section.

3. Check DEPENDENCIES.md boundary. Verify that nothing listed as an external dependency in DEPENDENCIES.md is contradicted by ENGINEERING.md requirements showing the system manages it internally (a stale dependency that was since internalized).

4. Check code traceability (embedded modules only). For embedded modules, search the codebase (excluding node_modules, vendor, .git, build output) for references to P-*, E-*, and D-DEP-* requirement IDs. Report:

   • Requirements referenced in code (good)
   • Requirements with no code references (potential coverage gaps)
   • Code references to IDs that don't exist in any document (stale tags)

   Skip this step for detached modules — they use forward references instead of inline code tags.

5. Check test coverage tags (embedded modules only). Search test files for requirement ID references. Report requirements that have implementation references but no test references. Skip for detached modules.

6. Check cross-module references. Validate that any cross-module ← backlinks (relative paths to other modules' documents) resolve to actual files and anchors.

Step 3: Print a combined report

Combine the CLI structural report with the semantic analysis into a single summary:

## ANCHORS Check Report

### Modules
- services/auth (prefix: AUTH) — 4/4 documents
- services/payments (prefix: PAY) — 3/4 documents (no DEPENDENCIES.md)
- platform/shared (prefix: SHLIB) — 1/4 documents (only ENGINEERING.md)
- apps/penpal/anchors (prefix: PENPAL, detached → ../penpal) — 3/4 documents
- docs/ext-api (prefix: EXTAPI, detached → github.com/org/api@main) — 3/4 documents

### Traceability (all modules)
- Engineering → PRD backlinks: 41/43 (2 missing)
- PRD coverage by Engineering: 28/28 (100%)
- Requirements in code (embedded): 52/71 (73%)
- Requirements in tests (embedded): 38/71 (54%)
- Forward references (detached): 12/14 (2 broken)

### Gaps

#### Missing Engineering Backlinks
- AUTH: E-AUTH-CACHE-TTL (no ← P-* link)
- PAY: E-PAY-LOG-FORMAT (no ← P-* link)

#### Uncovered Product Requirements (P-* with no E-* coverage)
(none)

#### Untraced Requirements (no code references — embedded modules)
- AUTH: P-AUTH-NOTIFY-SOUND
- SHLIB: E-SHLIB-RECOVERY-RESTART

#### Requirements Without Test References (embedded modules)
- PAY: E-PAY-WEBHOOK-RETRY (in code but not in tests)

#### Broken Forward References (detached modules)
- EXTAPI: E-EXTAPI-RATE-LIMIT → `src/middleware/rate.go:RateLimit` (file not found)
- EXTAPI: E-EXTAPI-AUTH-VERIFY → `src/auth/verify.go:VerifyToken` (symbol not found)

#### Stale Code References (embedded modules)
- src/legacy.go: references E-OLD-THING (not in any document)

#### Open Questions
- services/auth/PRODUCT.md: OPEN-MFA-FLOW (unresolved)

#### Structural Drift
- AUTH: TESTING.md has unrecognized section "Coverage Mapping" (not in canonical structure)
- PAY: TESTING.md missing required section "What We Deliberately Don't Test"

#### DEPENDENCIES.md Boundary Issues
(none)

---

Embed Mode

Convert a detached module to embedded mode. This adds inline requirement tags to source files based on → forward references, then strips the detached-mode artifacts from the docs. Only available for detached modules.

Determine the target module

1. If a path was given as an argument, use it.
2. If no path was given, check whether the current working directory has an ANCHORS.md with mode: detached.
   • Yes → use the current working directory.
   • No mode: detached → error: "This module is already in embedded mode."
   • No ANCHORS.md → error: "No ANCHORS module found in this directory."

Steps

1. Read the module. Read ANCHORS.md frontmatter to get mode, repo, ref, path. Read ENGINEERING.md and extract all → forward references (list of file:symbol pairs per E-* requirement).

2. Locate the code locally. The target code must be accessible on the local filesystem. Resolution:

   • In-repo (no repo): resolve path relative to the ANCHORS.md file. The code is already local.
   • External with local path: use repo directly, scoped to path.
   • External with remote URL: use AskUserQuestion to ask for the local path:
     • Question: "Where is the code locally? (e.g., you cloned or forked the repo)"
     • Header: "Code path"
     • Suggest the parent directory and common sibling paths.
   • Verify the resolved path exists and contains the expected files (spot-check a few → refs).

3. Add inline tags. For each → reference in ENGINEERING.md:

   • Resolve the file:symbol against the resolved target directory.
   • Find the function/symbol definition in the file.
   • Add an inline requirement tag comment above or on the function (e.g., // E-AUTH-SESSION: sessions use signed JWTs).
   • Follow the standard code traceability rules: one tag per function, augment existing comments, don't replace them.
   • If a → ref can't be resolved (file missing, symbol not found), skip it and report it at the end.

4. Update ENGINEERING.md. Remove all → lines. The ← backlinks are preserved unchanged.

5. Update ANCHORS.md. Remove the mode, repo, ref, and path fields from the frontmatter, leaving only prefix. This switches the module to embedded mode.

6. Report results. Print a summary:

   • Number of inline tags added