Carlos Florêncio
1.9 KiB
Specification Catalog
Kandev specifications describe product intent, required behavior, and system design. System README files define durable boundaries. Requirement and system-design files define the owned contracts.
This page is a static entry page. It does not contain a generated list of systems or documents. The specification files are the source of truth.
Find specifications
Run the catalog command from the repository root:
python3 scripts/list-docs.py specs --format markdown
Use filters for common discovery tasks:
python3 scripts/list-docs.py specs --system ui --kind requirement --format paths
python3 scripts/list-docs.py specs --status active --format markdown
python3 scripts/list-docs.py specs --text workflow --format json
The command recognizes these kinds:
- system: a system boundary README with specification frontmatter.
- glossary: a system glossary.md file.
- requirement: a document under a system requirements directory.
- system-design: a document under a system system-design directory.
- product: a product-wide document under docs/specs/product/.
- legacy: a document that remains outside the migrated layout.
Use paths for shell tools and JSON for structured consumers. The command sorts results deterministically and searches document text without changing the source files.
Validate specifications
Run both repository checks before you commit specification changes:
python3 scripts/list-docs.py validate
python3 scripts/lint-spec-files.py --all
The catalog validates the metadata it needs for discovery. The specification linter remains authoritative for IDs, cross-references, migration rules, and file-size limits.
Authoring rule
Keep system purpose, ownership, exclusions, migration history, and related links in each system README. Do not add catalog rows to this page or repeat requirement and system-design lists in a system README.