Skip to main content

Repository Structure for Adopters

Purpose: This document explains the ai-dev-kit repository structure from an adopter's perspective, clarifying which parts are frameworks (to copy/adopt), which are dev-kit-specific examples, and which are book/authoring content.

Framework Packages (Canonical - Copy These)​

Location: packages/frameworks/

These are the canonical framework packages that adopters should copy or install:

Numbering & Versioning Framework​

  • Path: packages/frameworks/numbering & versioning/
  • Canonical docs:
    • versioning-policy.md - Primary schema definition (RC.EPIC.STORY.TASK+BUILD)
    • versioning-strategy.md - Comprehensive strategy (ordering, timestamps, traceability)
    • README.md - Package overview
  • What to copy: Entire package directory

Workflow Management Framework​

  • Path: packages/frameworks/workflow mgt/
  • Canonical docs:
    • KB/Documentation/Developer_Docs/vwmp/release-workflow-agent-execution.md - RW agent execution guide
    • KB/Documentation/Developer_Docs/vwmp/update-kanban-workflow-agent-execution.md - UKW agent execution guide
    • KB/Documentation/Developer_Docs/vwmp/package-version-workflow-agent-execution.md - PVW agent execution guide
    • scripts/validation/* - Branch context, changelog, version validators
    • scripts/version/semver_converter.py - SemVer mapping logic
    • scripts/changelog/cmw.py - Changelog Management Workflow
  • What to copy: Entire package directory

Kanban Framework​

  • Path: packages/frameworks/kanban/
  • Canonical docs:
    • policies/kanban-governance-policy.md - Framework-level governance
    • templates/* - Epic/story/task and board guide templates
  • What to copy: Entire package directory

Dev-Kit Local Specialisations (Examples - Reference Only)​

Location: docs/architecture/standards-and-adrs/

These are dev-kit-specific applications of the frameworks. Adopters should create their own specialisations:

Versioning Policy​

  • Path: docs/architecture/standards-and-adrs/dev-kit-versioning-policy.md
  • Purpose: Dev-kit's application of the versioning framework (fixes Epic space 1-4+, documents dev-kit-specific SemVer mapping)
  • Framework SoT: packages/frameworks/numbering & versioning/versioning-policy.md
  • For adopters: Create your own policy that references the framework SoT and documents your project's Epic ranges and adaptations

Changelog Policies​

  • Paths:
    • docs/architecture/standards-and-adrs/changelog-management-policy.md
    • docs/architecture/standards-and-adrs/changelog-archival-policy.md
  • Purpose: Dev-kit's application of CMW patterns (latest-only mode, archival thresholds)
  • Framework SoT: packages/frameworks/workflow mgt/workflows/changelog-management-workflow.yaml
  • For adopters: Reference these as examples, but create your own policies based on your project's needs

Kanban Instance​

  • Path: docs/project-management/kanban/
  • Purpose: Dev-kit's actual Kanban board, epics, stories, tasks (an instance of the framework)
  • Framework SoT: packages/frameworks/kanban/policies/kanban-governance-policy.md
  • For adopters: Use the framework templates to create your own Kanban structure; don't copy dev-kit's actual epics/stories

Book/Authoring Content (Not for Adoption)​

Location: docs/documentation/, docs/knowledge/, various root-level docs

These are book project content and authoring materials, not framework documentation:

  • docs/documentation/user-docs/ - Book chapters and user guides
  • docs/knowledge/ - Author research and analysis
  • for-dummies-style-guide.md - Book style guide
  • Various authoring checklists and outlines

For adopters: Ignore these; they're for the book project, not framework adoption.

Adoption entry points (greenfield vs brownfield)​

Installer-driven greenfield setup is documented from repository root INSTALL_IN_YOUR_PROJECT.md (FR-080). Policy: ADR-003; brownfield modular integration: FR-081; planning package: IPW-E6S09T01.

Some paths under docs/documentation/user-docs/ support both book-style narrative and adoption workflows; framework adoption should treat INSTALL_IN_YOUR_PROJECT.md as the canonical first-run pointer unless a guide explicitly scopes brownfield work.

Scripts​

Framework Scripts (Copy These)​

  • Location: packages/frameworks/workflow mgt/scripts/ and packages/frameworks/kanban/scripts/
  • Purpose: Core workflow validators, converters, changelog management, Kanban installation
  • For adopters: Copy these scripts when installing frameworks

Project Utilities (Reference Only)​

  • Location: scripts/
  • Purpose: Dev-kit-specific utilities (framework package build/publish, documentation health monitoring, internal tooling)
  • For adopters: These are useful examples but not required for framework adoption

Project Root​

The project root is kept minimal. Only the following belong there:

  • README.md – Project overview and quick start
  • CHANGELOG.md – Main changelog (Keep a Changelog)
  • CONTRIBUTING.md – Contribution guidelines
  • INSTALL_IN_YOUR_PROJECT.md – How to install frameworks (adopter-facing)
  • Config files – e.g. rw-config.yaml, semver-registry.yaml

Maintainer runbooks (build packages, upload to releases, etc.) live in docs/maintenance/, not in root. See docs/maintenance/README.md.

Configuration Files​

rw-config.yaml​

  • Location: Project root
  • Purpose: Release Workflow configuration (paths, schema, Kanban integration)
  • For adopters: Create your own rw-config.yaml using the framework's config schema

semver-registry.yaml​

  • Location: Project root
  • Purpose: SemVer mapping registry (epic/story → MINOR/PATCH assignments)
  • For adopters: Create your own registry when adopting the versioning framework

Summary​

ItemLocationAdopter Action
Frameworks (SoT)packages/frameworks/*Copy entire packages
Dev-kit policiesdocs/architecture/standards-and-adrs/*Reference as examples, create your own
Dev-kit Kanbandocs/project-management/kanban/Use framework templates, don't copy dev-kit's epics
Framework scriptspackages/frameworks/*/scripts/Copy when installing frameworks
Project utilitiesscripts/Optional reference only
Book contentdocs/documentation/, docs/knowledge/Ignore (book project only)
Maintainer runbooksdocs/maintenance/Reference only (build/upload; not for adoption)

Key Principle: Frameworks (packages/frameworks/*) are the canonical source of truth. Dev-kit-local docs (docs/architecture/standards-and-adrs/*) are specialisations that show how to apply the frameworks in a specific project context.