first commit

Author: PredictabilityAtScale

.capabilities/capabilitykit.yaml

@@ -0,0 +1,19 @@
+schema_version: 0.1
+project:
+  name: capabilitykit
+  description: Capabilities as code for AI-native software teams.
+  repository: https://github.com/FocusedObjective/capabilitykit
+source:
+  include:
+    - "**/*.capability.yaml"
+  exclude:
+    - "dist/**"
+validation:
+  require_acceptance: true
+  require_verification: true
+  allow_verification_gaps: true
+  require_implementation_references_for_status:
+    - implemented
+    - verified
+output:
+  path: .capabilities/dist/capabilities.json

.capabilities/core/compile-capabilities.capability.yaml

@@ -0,0 +1,37 @@
+id: core.compile-capabilities
+title: Compile capabilities
+status: implemented
+area: core
+summary: Compile capability YAML files into normalized JSON with validation and verification summary data.
+intent: Provide a machine-readable capability map that tools and agents can consume consistently.
+inputs:
+  - .capabilities/**/*.capability.yaml
+outputs:
+  - .capabilities/dist/capabilities.json
+depends_on:
+  - core.define-capability
+  - core.validate-capabilities
+acceptance:
+  - Writes normalized JSON to the configured output path.
+  - Includes project metadata and all parsed capabilities.
+  - Includes dependency graph information.
+  - Includes validation results and verification summary.
+verification:
+  automated:
+    - id: compile-tests
+      description: Unit tests verify compiled output shape.
+      command: npm test
+    - id: dogfood-compile
+      description: The CLI compiles CapabilityKit's own capability map.
+      command: npm run capabilitykit -- compile
+  manual:
+    - Inspect .capabilities/dist/capabilities.json after compile and confirm the graph is readable.
+implementation:
+  references:
+    - packages/core/src/compileCapabilities.ts
+    - packages/cli/src/index.ts
+agent_guidance:
+  build_notes:
+    - Include validation output in the compiled artifact so downstream tools can detect risk.
+  avoid:
+    - Do not emit partial JSON without surfacing validation failures.

.capabilities/core/define-capability.capability.yaml

@@ -0,0 +1,34 @@
+id: core.define-capability
+title: Define capability format
+status: implemented
+area: core
+summary: Define the YAML schema and TypeScript types for repo-native capability specs.
+intent: Give humans and AI coding agents a shared source of intent, scope, acceptance criteria, and verification expectations.
+inputs:
+  - .capabilities/**/*.capability.yaml
+outputs:
+  - TypeScript schema
+  - parsed capability objects
+depends_on: []
+acceptance:
+  - Capability files require id, title, status, area, summary, intent, and acceptance criteria.
+  - Verification checks can include automated commands, manual review guidance, and known gaps.
+  - Implementation references can point from capability specs to source files.
+verification:
+  automated:
+    - id: parser-tests
+      description: Unit tests cover valid and invalid capability parsing.
+      command: npm test
+  manual:
+    - Review the example capability file in the README for clarity.
+implementation:
+  references:
+    - packages/core/src/schema.ts
+    - packages/core/src/types.ts
+    - packages/core/src/parseCapability.ts
+agent_guidance:
+  build_notes:
+    - Keep the MVP format small and deterministic.
+    - Update this spec whenever the schema changes.
+  avoid:
+    - Do not make cloud services required for schema validation.

.capabilities/core/detect-verification-gaps.capability.yaml

@@ -0,0 +1,32 @@
+id: core.detect-verification-gaps
+title: Detect verification gaps
+status: implemented
+area: core
+summary: Identify missing or weak verification information in capability specs.
+intent: Reduce the human bottleneck by making review needs explicit before maintainers inspect code manually.
+inputs:
+  - parsed capability objects
+outputs:
+  - verification gap list
+depends_on:
+  - core.define-capability
+acceptance:
+  - Reports capabilities with no automated checks.
+  - Reports capabilities with no manual review guidance.
+  - Reports implemented or verified capabilities without implementation references.
+  - Reports declared verification gaps from capability files.
+verification:
+  automated:
+    - id: verification-gap-tests
+      description: Unit tests cover deterministic verification gap detection.
+      command: npm test
+  manual:
+    - Review validation output and confirm gaps explain what a human still needs to check.
+implementation:
+  references:
+    - packages/core/src/validateCapabilities.ts
+agent_guidance:
+  build_notes:
+    - Prefer specific gap messages tied to capability IDs.
+  avoid:
+    - Do not use AI inference for MVP verification gap detection.

.capabilities/core/initialize-project.capability.yaml

@@ -0,0 +1,33 @@
+id: core.initialize-project
+title: Initialize capability project
+status: implemented
+area: core
+summary: Create a starter .capabilities folder with config and an example capability.
+intent: Help teams adopt capabilities as code with a small, understandable first step.
+inputs:
+  - current working directory
+outputs:
+  - .capabilities/capabilitykit.yaml
+  - .capabilities/example.capability.yaml
+depends_on:
+  - core.define-capability
+acceptance:
+  - Creates the root capability config file.
+  - Creates a starter capability file.
+  - Refuses to overwrite existing files unless force is requested.
+  - Prints practical next steps.
+verification:
+  automated:
+    - id: cli-build
+      description: The CLI builds successfully.
+      command: npm run build
+  manual:
+    - Run capabilitykit init in a temporary folder and confirm starter files are valid.
+implementation:
+  references:
+    - packages/cli/src/index.ts
+agent_guidance:
+  build_notes:
+    - Generated files should pass capabilitykit validate.
+  avoid:
+    - Do not overwrite user capability files by default.

.capabilities/core/validate-capabilities.capability.yaml

@@ -0,0 +1,39 @@
+id: core.validate-capabilities
+title: Validate capability files
+status: implemented
+area: core
+summary: Validate schema correctness, duplicate IDs, broken dependencies, and verification gaps.
+intent: Make changes safer by giving humans and agents a repeatable check before review.
+inputs:
+  - .capabilities/**/*.capability.yaml
+outputs:
+  - validation report
+  - verification gap list
+depends_on:
+  - core.define-capability
+acceptance:
+  - Reports YAML and schema errors with file paths.
+  - Detects duplicate capability IDs.
+  - Detects broken depends_on references.
+  - Reports missing automated checks, missing manual review guidance, and missing implementation references.
+verification:
+  automated:
+    - id: validation-tests
+      description: Unit tests cover duplicate IDs, broken dependencies, and verification gaps.
+      command: npm test
+    - id: dogfood-validate
+      description: The CLI validates CapabilityKit's own capability map.
+      command: npm run capabilitykit -- validate
+  manual:
+    - Confirm validation output is actionable enough to reduce manual review guesswork.
+implementation:
+  references:
+    - packages/core/src/validateCapabilities.ts
+    - packages/core/src/loadCapabilities.ts
+    - packages/cli/src/index.ts
+agent_guidance:
+  build_notes:
+    - Treat verification gaps as warnings by default.
+    - Keep validation deterministic in the MVP.
+  avoid:
+    - Do not silently ignore malformed capability files.

.capabilities/developer-experience/cli-workflow.capability.yaml

@@ -0,0 +1,36 @@
+id: developer-experience.cli-workflow
+title: CLI workflow
+status: implemented
+area: developer-experience
+summary: Provide CLI commands for init, create, validate, compile, and inspect.
+intent: Make capability management fast enough to stay close to normal development workflows.
+inputs:
+  - terminal commands
+  - capability files
+outputs:
+  - created capability files
+  - validation reports
+  - compiled JSON
+depends_on:
+  - core.initialize-project
+  - core.validate-capabilities
+  - core.compile-capabilities
+acceptance:
+  - Supports init, create, validate, compile, and inspect commands.
+  - Returns a non-zero exit code for validation failures.
+  - Prints verification gaps in validation and inspect output.
+verification:
+  automated:
+    - id: cli-build
+      description: TypeScript build verifies CLI entrypoint imports.
+      command: npm run build
+  manual:
+    - Run each CLI command against the dogfooded capability map before release.
+implementation:
+  references:
+    - packages/cli/src/index.ts
+agent_guidance:
+  build_notes:
+    - Keep command output concise and script-friendly.
+  avoid:
+    - Do not hide verification gaps behind verbose flags.

.capabilities/developer-experience/example-project.capability.yaml

@@ -0,0 +1,32 @@
+id: developer-experience.example-project
+title: Example project
+status: implemented
+area: developer-experience
+summary: Provide a small example app capability map for users to inspect.
+intent: Show how product capabilities can be grouped by area and connected with dependencies.
+inputs:
+  - examples/basic-app/.capabilities
+outputs:
+  - example capability files
+depends_on:
+  - core.define-capability
+acceptance:
+  - Includes account and checkout capability areas.
+  - Example files include verification sections.
+  - Example files are valid against the MVP schema.
+verification:
+  automated:
+    - id: parser-tests
+      description: Unit tests load example capability shapes.
+      command: npm test
+  manual:
+    - Read the example files and confirm they are understandable without extra docs.
+implementation:
+  references:
+    - examples/basic-app/.capabilities/capabilitykit.yaml
+    - examples/basic-app/.capabilities/account/login.capability.yaml
+agent_guidance:
+  build_notes:
+    - Keep examples realistic but compact.
+  avoid:
+    - Do not add app code that distracts from capability files.

.capabilities/developer-experience/vscode-extension.capability.yaml

@@ -0,0 +1,29 @@
+id: developer-experience.vscode-extension
+title: VS Code extension readiness
+status: planned
+area: developer-experience
+summary: Keep the package structure ready for a future VS Code extension without implementing it in the MVP.
+intent: Preserve a path toward editor diagnostics, navigation, and capability tree views.
+inputs:
+  - compiled capabilities JSON
+outputs:
+  - future editor integration points
+depends_on:
+  - core.compile-capabilities
+acceptance:
+  - MVP does not include VS Code extension code.
+  - Compiled JSON contains enough path and graph data for a future extension.
+verification:
+  automated:
+    - id: compile-tests
+      description: Compile tests cover path and graph data needed by future tools.
+      command: npm test
+  manual:
+    - Review compiled JSON and confirm it contains capability paths and dependencies.
+implementation:
+  references: []
+agent_guidance:
+  build_notes:
+    - Design output data to be editor-friendly.
+  avoid:
+    - Do not implement extension UI during the MVP.

.capabilities/docs/capability-format.capability.yaml

@@ -0,0 +1,32 @@
+id: docs.capability-format
+title: Capability format documentation
+status: implemented
+area: docs
+summary: Document the capability YAML fields and verification gap model.
+intent: Help developers write useful specs without treating CapabilityKit as heavyweight process.
+inputs:
+  - README.md
+  - .capabilities/**/*.capability.yaml
+outputs:
+  - documented capability format
+depends_on:
+  - core.define-capability
+acceptance:
+  - README explains what a capability is.
+  - README includes an example capability file.
+  - README explains verification gaps.
+verification:
+  automated:
+    - id: dogfood-validate
+      description: The docs capability is validated as part of the project capability map.
+      command: npm run capabilitykit -- validate
+  manual:
+    - Read README from a new user's perspective and confirm the format is clear.
+implementation:
+  references:
+    - README.md
+agent_guidance:
+  build_notes:
+    - Use practical developer language.
+  avoid:
+    - Avoid UML, enterprise architecture, and governance-heavy framing.