Spec

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

.claude/agents

.claude/skills

.github/CLAUDE.md

CLAUDE.md

apps/backend/CLAUDE.md

import { test, expect } from "../../fixtures/test-base";

apps/web/generated/licenses.json

Audit 0.4.1 · source sha 786d4817799e · 18 Oct 2026Report an issue or request a re-scan

• Publisherkdlbs GitHub organizationOwner of the repository this skill is read from
• Source folderkdlbs/kandev/.agents/skills/specThe exact folder we audited
• LicenceAGPL-3.0As the repository states it
• Commit pinned for this verdict786d4817799eA new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Create or update Kandev product requirements and system-design documents before implementation. Use for new product behavior, changed contracts, or explicit specification work. Do not use for implementation plans, work…

---
name: spec
description: Create or update Kandev product requirements and system-design documents before implementation. Use for new product behavior, changed contracts, or explicit specification work. Do not use for implementation plans, work orders, incidents, or behavior-preserving refactors.
---

# Specification Authoring

Use this skill to create or update durable specifications. Requirements define
observable behavior. System designs define the technical path that satisfies
requirements.

The canonical rules are in `docs/specs/guide/`. Read these files before you
write an artifact:

- Always read `structure-and-ownership.md`.
- Read `requirements.md` for requirement work.
- Read `system-design.md` for system-design work.
- Read `traceability-and-lifecycle.md` for IDs, statuses, references, or
  migration work.

Use the templates in `docs/specs/templates/`.

## Artifact routing

Route the request before you write:

| Request | Artifact |
| --- | --- |
| Kandev-wide purpose, actors, principles, measures, or constraints | `docs/specs/product/` |
| Observable behavior for one owning system | `<system>/requirements/` |
| Technical contracts, models, boundaries, or control flow | `<system>/system-design/` |
| Durable choice with meaningful alternatives | `/record` and an ADR |
| Delivery sequence and implementation tasks | `/plan` |
| Incident or behavior-preserving refactor | No product requirement |
| Bug | `/fix`, which checks the existing requirement first |

Do not create a generic `spec.md` file.

When routing to `docs/specs/product/`, read `docs/specs/product/README.md`
before editing. Treat its **Product document index** as the local index: read
every linked product document and any co-located `INDEX.md`, `AGENTS.md`,
`CLAUDE.md`, or other instruction file when present. Product files provide
cross-system context, not feature requirements; preserve proposed and
open-question language instead of promoting it to an active contract without
confirmation.

## Workflow

### 1. Locate the owning system

Read `docs/specs/README.md` and the likely system `README.md`. If the system
has not migrated, run this command to locate the legacy source:

    python3 scripts/list-docs.py specs --kind legacy --format paths

Search the catalog, requirements, and designs for the capability name and its
main nouns:

    python3 scripts/list-docs.py specs --text <capability-term> --format paths

Update an existing capability when it owns the same actor, lifecycle, and
contract.

Choose the system that owns the source of truth and durable contract. Do not
choose an owner from the code directories that change. Record one sentence in
the working notes that states why the selected system owns the capability.

User visibility does not make a capability UI-owned. Keep provider state, task
state, permissions, persistence, and recovery with their owning systems. Put
desktop, mobile, accessibility, and visible failure outcomes in that owner's
requirement. Create a UI requirement only for an independent and reusable
presentation contract.

The same system owns the requirement and its design. Other systems link to that
source. They do not copy it or claim its requirement IDs in design frontmatter.

If no system owns the behavior, define the new system boundary before you write
requirements. A new system needs a `README.md` based on the system template.

### 2. Confirm intent

Run the `/interview-me` assumption check, reusing answers from earlier phases.
Resolve material choices before writing the affected contract. Preserve settled
terminology and decision rationale in the owning artifacts through that skill.
Do not hide an unresolved choice in a draft.

### 3. Write requirements

Create or update:

```text
docs/specs/<system>/requirements/<capability>.md
```

Each requirement document must contain:

- Valid frontmatter.
- One or more stable `REQ-*` IDs.
- At least one `AC-*` acceptance criterion for each requirement.
- Observable behavior and explicit exclusions.

Use user stories only when they clarify a natural actor and outcome. Do not put
files, functions, database queries, or implementation sequences in a
requirement.

Keep one cohesive vertical outcome together. Do not create separate backend and
UI requirements for the same feature. Split only when actors, lifecycles, or
contracts are independent.

### 4. Write system design

Create or update this file when the change needs a technical design:

```text
docs/specs/<system>/system-design/<capability>.md
```

The design must list the applicable `REQ-*` IDs in frontmatter. It can use an
explicit empty list for internal infrastructure with no independent product
requirement.

Describe stable components, models, contracts, flow, failure behavior,
persistence, security, and observability when they apply. Link to global ADRs.
Do not copy requirement or ADR text.

Cover all runtime boundaries that implement the owned outcome. A provider-owned
design can include backend services, storage, projections, frontend components,
responsive behavior, and tests. Do not create a parallel UI design for those
same requirements.

### 5. Update the system boundary

Update the system `README.md` only when the system boundary, migration record,
or related-system links change. State the system boundary and link adjacent
systems when ownership can be confused. Do not add a requirement or
system-design list.

Before and after adding required links, run `wc -c <system>/README.md`. Near
the 12 KiB `system-index` limit, keep every required link but use concise
labels or other non-semantic compression; never add a size exception. Rerun
the specification linter after the index update. Also search the README for
count or list summaries, update them when the authoritative pair count changes,
and verify that each stated count matches the indexed requirement/design pairs.

During migration, name the new source as authoritative. Replace the old source
with a link or archive it. Do not leave tw

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/kdlbs/kandev
git -C kandev checkout 786d4817799e

Works in

1. 2026-10-18
   !CAUTION B 89 / 100

   first audit · source 786d4817799e

Questions about Spec

• github.com/kdlbs/kandev/tree/main/.agents/skills/spec — the audited source at commit 786d4817799e and every finding aboveObserved · 18 Oct 2026

Spotted something wrong? Report a correction · Methodology