5.4 KiB
Structure and Ownership
Specification root
docs/specs is the root for durable Kandev specifications. The directory uses
systems as its primary organization.
docs/specs/
├── product/
└── <system>/
├── README.md
├── glossary.md
├── requirements/
└── system-design/
A system owns a stable set of concepts, behavior, and technical boundaries. Examples include the task system, agent runtime, plugin system, and GitHub integration.
System test
Create a system directory when at least two statements are true:
- The system owns a stable vocabulary or data model.
- Multiple consumers depend on its behavior or guarantees.
- The system has an independent lifecycle.
- A team can design and review its changes independently.
- Several features or other systems depend on it.
Do not create a system for one helper, component, page, or endpoint. Put that design in the system that owns the behavior.
System ownership
Each requirement has one owning system. Another system can reference the requirement but must not copy it.
Each system has a README.md. This file defines the system boundary, migration
record, and related systems. Use glossary.md only when the system has terms
that need precise definitions.
Use the catalog command to find the documents that a system owns:
python3 scripts/list-docs.py specs --system <system-slug> --format markdown
python3 scripts/list-docs.py specs --system <system-slug> --kind requirement --format paths
python3 scripts/list-docs.py specs --system <system-slug> --kind system-design --format paths
The command derives its results from paths and frontmatter. Do not copy its results into a system README.
The system README sets migration: in_progress while legacy files remain. Set
it to complete only after the new authoritative documents exist and all
editable legacy sources become links or archives. The catalog command discovers
the files, and the linter enforces the strict system layout after migration is
complete.
A system does not need both artifact directories. A low-level system can have system designs without product requirements. Do not create empty placeholder documents.
Product specifications
docs/specs/product contains Kandev-wide context. It can contain these files:
overview.mdexplains the product problem and boundary.actors.mddefines people, agents, plugins, and external systems.product-map.mdmaps the systems and their relationships.principles.mddefines durable product principles.success-measures.mddefines measures that the team uses.product-constraints.mddefines cross-system quality and compatibility requirements.
Do not put feature requirements, API details, roadmaps, or work status in the product directory.
Cross-system design
The system that owns a contract also owns its design. Other system designs link to that contract. Do not create a separate shared-design tree only because two systems use the same capability.
Create a first-class system when shared behavior has independent ownership and guarantees. Event delivery and persistence can become systems under this rule.
Vertical feature ownership
Choose the owner from the durable contract, not from the code directories that the implementation changes. A capability can change backend, frontend, mobile, and test code while one system owns its requirements and design.
User visibility does not make a capability UI-owned. The UI system owns an interaction contract only when that contract remains useful without the feature or backend state that first uses it. Provider state, task state, permissions, and persistence stay with their owning systems. Their requirements can include desktop, mobile, accessibility, and failure outcomes.
For example, a GitHub merge-queue capability belongs to the integration system. Its integration requirement describes the visible queue controls and states. Its integration design describes the GitHub client, persistence, API projection, and React components. Do not create a second UI requirement or design for those same controls.
Create separate cross-system artifacts only when each system owns an independent contract with a different lifecycle. Link the contracts in both documents. Do not repeat acceptance criteria or technical sections.
File names
Use a short kebab-case capability name. Use the same file name for the paired requirement and system design when practical.
task-system/requirements/dependencies.md
task-system/system-design/dependencies.md
Do not create new files named spec.md. The file name must identify the
capability.
Context limits
The specification linter reads the default limits from docs/specs/spec-lint.json.
The default limits are:
- System README: 16 KiB.
- Product or guide document: 16 KiB.
- Requirement document: 20 KiB.
- System-design document: 32 KiB.
- Template: 8 KiB.
- Unmigrated legacy specification: 32 KiB.
Split a file before it reaches its limit. Split by capability, lifecycle, or contract boundary. Do not split by arbitrary line ranges.
An oversized legacy file can have a frozen ceiling registered in
docs/specs/spec-lint-exceptions.tsv (one path<TAB>size record per line).
The path must identify a regular legacy Markdown file under docs/specs.
The ceiling permits migration work but does not permit growth. Lower the ceiling
in the same change whenever the file shrinks. Remove the exception after the
file falls below the default limit.