website

PredictabilityAtScale · PredictabilityAtScale · commit 2b05e544b0f7 · 2026-05-10T18:14:55.000-07:00
diff --git a/.capabilities/core/assess-implementation-coverage.capability.yaml b/.capabilities/core/assess-implementation-coverage.capability.yaml
@@ -0,0 +1,38 @@
+id: core.assess-implementation-coverage
+title: Assess implementation coverage
+status: planned
+area: core
+summary: Compare a capability's acceptance criteria with its referenced implementation files to help determine whether the code covers the declared behavior.
+intent: Move beyond checking that implementation paths exist by giving humans and agents a focused evidence bundle for capability review.
+inputs:
+  - capability acceptance criteria
+  - capability implementation.references values
+  - referenced source and documentation files
+outputs:
+  - implementation coverage report
+  - uncovered or uncertain acceptance criteria
+depends_on:
+  - core.verify-implementation-references
+acceptance:
+  - Reads the referenced implementation files for one capability.
+  - Presents each acceptance criterion beside relevant implementation evidence.
+  - Marks criteria as covered, uncovered, or uncertain.
+  - Reports missing or unreadable references as uncovered evidence.
+  - Keeps the first version deterministic or review-assisted rather than silently trusting an AI judgment.
+verification:
+  automated:
+    - id: coverage-report-tests
+      description: Unit tests cover report generation for covered, uncovered, and missing-reference cases.
+      command: npm test
+  manual:
+    - Run the coverage report against core.verify-implementation-references and confirm the output gives a reviewer enough context to judge the implementation.
+  gaps:
+    - The first version should not claim semantic correctness without human or explicit AI review.
+implementation:
+  references: []
+agent_guidance:
+  build_notes:
+    - Start with a deterministic evidence report that loads capability details and referenced files.
+    - Add an agentic or LLM review loop only after the report shape is useful and testable.
+  avoid:
+    - Do not mark capabilities verified solely because referenced files contain matching words.
diff --git a/.capabilities/core/detect-verification-gaps.capability.yaml b/.capabilities/core/detect-verification-gaps.capability.yaml
@@ -28,5 +28,6 @@ implementation:
 agent_guidance:
   build_notes:
     - Prefer specific gap messages tied to capability IDs.
+    - Keep gap detection rules deterministic and covered by automated tests.
   avoid:
     - Do not use AI inference for MVP verification gap detection.
diff --git a/.capabilities/core/verify-implementation-references.capability.yaml b/.capabilities/core/verify-implementation-references.capability.yaml
@@ -0,0 +1,36 @@
+id: core.verify-implementation-references
+title: Verify implementation references
+status: implemented
+area: core
+summary: Confirm implemented and verified capabilities point to implementation references that exist in the repository.
+intent: Help maintainers and agents trust that completed capabilities are tied to inspectable code or documentation.
+inputs:
+  - .capabilities/**/*.capability.yaml
+  - implementation.references values
+outputs:
+  - verification gap list
+depends_on:
+  - core.validate-capabilities
+acceptance:
+  - Checks implementation references for capabilities marked implemented or verified.
+  - Reports a verification gap when a referenced implementation path does not exist.
+  - Does not report a gap for implementation references that resolve under the project root.
+verification:
+  automated:
+    - id: implementation-reference-tests
+      description: Unit tests cover existing and missing implementation reference targets.
+      command: npm test
+    - id: dogfood-validate
+      description: The CLI validates CapabilityKit's own capability map and implementation references.
+      command: npm run capabilitykit -- validate
+  manual:
+    - Break one implementation reference locally and confirm validation reports the missing path.
+implementation:
+  references:
+    - packages/core/src/validateCapabilities.ts
+    - packages/core/tests/validation.test.ts
+agent_guidance:
+  build_notes:
+    - Treat missing reference targets as verification gaps so validation remains advisory by default.
+  avoid:
+    - Do not require planned capabilities to have implementation references.
diff --git a/.capabilities/developer-experience/install-agent-guidance.capability.yaml b/.capabilities/developer-experience/install-agent-guidance.capability.yaml
@@ -0,0 +1,45 @@
+id: developer-experience.install-agent-guidance
+title: Install agent guidance
+status: implemented
+area: developer-experience
+summary: Initialize Codex, Claude, and AGENTS guidance files that point agents to CapabilityKit's package skill guide.
+intent: Make CapabilityKit review and editing workflows reusable across coding agents without copying long instructions into every project file.
+inputs:
+  - terminal command
+  - existing AGENTS.md or CLAUDE.md files
+  - package skill guide path
+outputs:
+  - AGENTS.md managed CapabilityKit block
+  - CLAUDE.md managed CapabilityKit block
+  - .codex/skills/capabilitykit/SKILL.md wrapper
+  - .claude/commands/capabilitykit.md slash command
+depends_on:
+  - developer-experience.cli-workflow
+acceptance:
+  - Provides a CLI command that installs CapabilityKit agent guidance files.
+  - Points generated guidance back to the package SKILL.md file.
+  - Preserves existing AGENTS.md and CLAUDE.md content while replacing any prior CapabilityKit managed block.
+  - Creates Codex skill and Claude slash-command wrapper files for simple prompts.
+  - Covers merge behavior with automated tests.
+verification:
+  automated:
+    - id: agent-guidance-tests
+      description: Unit tests cover managed block append and replacement behavior.
+      command: npm test
+    - id: cli-build
+      description: TypeScript build verifies the installer command and helper imports.
+      command: npm run build
+  manual:
+    - Run capabilitykit install-agent-guidance in a sample project and confirm the generated files reference the package SKILL.md.
+implementation:
+  references:
+    - packages/cli/SKILL.md
+    - packages/cli/src/agentGuidance.ts
+    - packages/cli/src/index.ts
+    - packages/cli/tests/agentGuidance.test.ts
+agent_guidance:
+  build_notes:
+    - Keep managed blocks short and bounded by stable markers.
+    - Prefer referencing the package skill guide over duplicating the full guide into project files.
+  avoid:
+    - Do not overwrite user-authored agent instructions outside the managed CapabilityKit block.
diff --git a/.claude/commands/capabilitykit.md b/.claude/commands/capabilitykit.md
@@ -0,0 +1,11 @@
+<!-- capabilitykit:start -->
+# capabilitykit
+
+This project uses **CapabilityKit** to manage capabilities as code.
+Read the full guide at `node_modules/@capabilitykit/cli/SKILL.md` before creating,
+editing, validating, reviewing, or implementing capability files.
+<!-- capabilitykit:end -->
+
+Help with this CapabilityKit task:
+
+$ARGUMENTS
diff --git a/.codex/skills/capabilitykit/SKILL.md b/.codex/skills/capabilitykit/SKILL.md
@@ -0,0 +1,14 @@
+---
+name: capabilitykit
+description: Work with CapabilityKit capabilities as code. Use when creating, editing, validating, compiling, reviewing, or comparing .capability.yaml files against implementation references.
+---
+
+# CapabilityKit
+
+<!-- capabilitykit:start -->
+# capabilitykit
+
+This project uses **CapabilityKit** to manage capabilities as code.
+Read the full guide at `node_modules/@capabilitykit/cli/SKILL.md` before creating,
+editing, validating, reviewing, or implementing capability files.
+<!-- capabilitykit:end -->
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,7 @@
+<!-- capabilitykit:start -->
+# capabilitykit
+
+This project uses **CapabilityKit** to manage capabilities as code.
+Read the full guide at `node_modules/@capabilitykit/cli/SKILL.md` before creating,
+editing, validating, reviewing, or implementing capability files.
+<!-- capabilitykit:end -->
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,7 @@
+<!-- capabilitykit:start -->
+# capabilitykit
+
+This project uses **CapabilityKit** to manage capabilities as code.
+Read the full guide at `node_modules/@capabilitykit/cli/SKILL.md` before creating,
+editing, validating, reviewing, or implementing capability files.
+<!-- capabilitykit:end -->
diff --git a/README.md b/README.md
@@ -107,3 +107,16 @@ Keep changes close to the code, specs, and tests they affect. When behavior chan
 ```bash
 npm run verify
 ```
+
+## Website (capabilitykit.com)
+
+A simple static marketing site is available in `website/` and is ready for Amazon S3 static hosting.
+
+Run locally:
+
+```bash
+cd website
+python3 -m http.server 8080
+```
+
+Then open `http://localhost:8080`.
diff --git a/packages/cli/SKILL.md b/packages/cli/SKILL.md
@@ -0,0 +1,37 @@
+---
+name: capabilitykit
+description: Work with CapabilityKit capabilities as code. Use when creating, editing, validating, compiling, reviewing, or comparing .capability.yaml files against implementation references.
+---
+
+# CapabilityKit
+
+Use CapabilityKit to keep product intent, acceptance criteria, implementation references, and verification checks close to the code.
+
+## Workflow
+
+1. Read `.capabilities/capabilitykit.yaml` to understand project settings.
+2. Read the relevant `*.capability.yaml` files before editing code for that behavior.
+3. When behavior changes, update the matching capability spec in the same change.
+4. Run `capabilitykit validate` to catch schema, dependency, verification, and implementation-reference gaps.
+5. Run `capabilitykit compile` to update `.capabilities/dist/capabilities.json`.
+
+## Implementation Review
+
+When asked whether a capability matches implementation behavior:
+
+1. Treat the capability file as the source of truth.
+2. Inspect every path in `implementation.references`.
+3. Compare each acceptance criterion with concrete code, test, or documentation evidence.
+4. Report each criterion as `covered`, `partially covered`, `not covered`, or `uncertain`.
+5. Do not infer coverage from filenames alone.
+6. Recommend the smallest code, test, or capability-spec change for each gap.
+
+## Useful Commands
+
+```bash
+capabilitykit create "User login" --area account
+capabilitykit validate
+capabilitykit inspect account.login
+capabilitykit compile
+capabilitykit install-agent-guidance
+```
diff --git a/packages/cli/package.json b/packages/cli/package.json
@@ -7,7 +7,8 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "SKILL.md"
   ],
   "bin": {
     "capabilitykit": "dist/index.js"
diff --git a/packages/cli/src/agentGuidance.ts b/packages/cli/src/agentGuidance.ts
@@ -0,0 +1,129 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+const blockStart = "<!-- capabilitykit:start -->";
+const blockEnd = "<!-- capabilitykit:end -->";
+
+export interface AgentGuidanceFile {
+  path: string;
+  contents: string;
+  block: string;
+}
+
+export interface InstallAgentGuidanceOptions {
+  packageSkillPath?: string;
+}
+
+export interface InstallAgentGuidanceResult {
+  written: string[];
+}
+
+function managedBlock(packageSkillPath: string): string {
+  return `${blockStart}
+# capabilitykit
+
+This project uses **CapabilityKit** to manage capabilities as code.
+Read the full guide at \`${packageSkillPath}\` before creating,
+editing, validating, reviewing, or implementing capability files.
+${blockEnd}`;
+}
+
+function codexSkillContents(packageSkillPath: string): string {
+  return `---
+name: capabilitykit
+description: Work with CapabilityKit capabilities as code. Use when creating, editing, validating, compiling, reviewing, or comparing .capability.yaml files against implementation references.
+---
+
+# CapabilityKit
+
+${managedBlock(packageSkillPath)}
+`;
+}
+
+function claudeCommandContents(packageSkillPath: string): string {
+  return `${managedBlock(packageSkillPath)}
+
+Help with this CapabilityKit task:
+
+$ARGUMENTS
+`;
+}
+
+export function mergeManagedBlock(existing: string | undefined, block: string): string {
+  const trimmedBlock = block.trim();
+  if (!existing || existing.trim().length === 0) {
+    return `${trimmedBlock}\n`;
+  }
+
+  const pattern = new RegExp(`${escapeRegExp(blockStart)}[\\s\\S]*?${escapeRegExp(blockEnd)}`, "m");
+  if (pattern.test(existing)) {
+    return existing.replace(pattern, trimmedBlock);
+  }
+
+  return `${existing.replace(/\s*$/, "")}\n\n${trimmedBlock}\n`;
+}
+
+export function buildAgentGuidanceFiles(options: InstallAgentGuidanceOptions = {}): AgentGuidanceFile[] {
+  const packageSkillPath = options.packageSkillPath ?? "node_modules/@capabilitykit/cli/SKILL.md";
+  const block = managedBlock(packageSkillPath);
+
+  return [
+    {
+      path: "AGENTS.md",
+      contents: block,
+      block
+    },
+    {
+      path: "CLAUDE.md",
+      contents: block,
+      block
+    },
+    {
+      path: ".codex/skills/capabilitykit/SKILL.md",
+      contents: codexSkillContents(packageSkillPath),
+      block
+    },
+    {
+      path: ".claude/commands/capabilitykit.md",
+      contents: claudeCommandContents(packageSkillPath),
+      block
+    }
+  ];
+}
+
+export async function installAgentGuidance(
+  rootDir: string,
+  options: InstallAgentGuidanceOptions = {}
+): Promise<InstallAgentGuidanceResult> {
+  const files = buildAgentGuidanceFiles(options);
+  const written: string[] = [];
+
+  for (const file of files) {
+    const filePath = path.join(rootDir, file.path);
+    const existing = await readOptional(filePath);
+    const nextContents = existing === undefined
+      ? file.contents
+      : mergeManagedBlock(existing, file.block);
+
+    await fs.mkdir(path.dirname(filePath), { recursive: true });
+    await fs.writeFile(filePath, nextContents);
+    written.push(file.path);
+  }
+
+  return { written };
+}
+
+async function readOptional(filePath: string): Promise<string | undefined> {
+  try {
+    return await fs.readFile(filePath, "utf8");
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts
diff --git a/packages/cli/tests/agentGuidance.test.ts b/packages/cli/tests/agentGuidance.test.ts
diff --git a/packages/core/src/validateCapabilities.ts b/packages/core/src/validateCapabilities.ts
diff --git a/packages/core/tests/validation.test.ts b/packages/core/tests/validation.test.ts
diff --git a/website/index.html b/website/index.html
diff --git a/website/styles.css b/website/styles.css
