Capabilities

/capabilities [subcommand] [arguments]

Single entry point for the project capability index. Capabilities describe what the project can do — organized by domain, with types that distinguish core capabilities from emergent compositions and refinements.

Hierarchy: domain → capability. Domains group capabilities by area of system function (e.g., data-management, security, query). Each domain has its own index. Capabilities are the leaf entries.

Three capability types:

• core — primary user-visible capability
• emergent — arises from composition of other capabilities (no single feature created it)
• refinement — quality/performance improvement to an existing domain area

Feature mapping: many-to-many with roles (core, extends, quality, enables). A feature can contribute to multiple capabilities.

Subcommands

Default (no subcommand): if the first argument looks like a question rather than a subcommand name, treat it as /capabilities "<question>".

Pre-flight guard

Check that .capabilities/CLAUDE.md exists. If not:

No capability index found. Would you like to set one up?

Use AskUserQuestion:

• "Set up now" — create .capabilities/CLAUDE.md with the seed template (see Setup section below), then continue
• "Not now" — stop

capabilities "" — natural language search

Search the capability index for entries matching a natural language query. This is the primary discovery mechanism — users ask "do we support X?" and get a structured answer.

Step 1 — Read the index

Read .capabilities/CLAUDE.md. Extract the domain map.

Step 2 — Match against domain indexes

For each domain, read its CLAUDE.md index. Match the query against:

1. Capability title (strongest signal)
2. Tags (query keywords against tags)
3. Domain description (broader match)

Only read full capability entry files for entries whose title or tags partially match. This keeps the search cheap.

Step 3 — Present results

Match found (1-3 results): Read the matching capability entry files. Display:

Found <n> matching capabilities:

  <title> (<type>, <status>) — <domain>
  <first 2-3 sentences of "What it does">

  Specs: <spec_refs>
  Decisions: <decision_refs>
  KB: <kb_refs>
  Features: <feature count> (<feature descriptions, abbreviated>)

  Full entry: .capabilities/<domain>/<slug>.md

For emergent capabilities, also show:

  Composes: <list of composed capabilities>

Multiple matches (4+): Display a summary table and let the user pick:

Use AskUserQuestion with one option per match (up to 4) plus "Other" for the full list.

No match:

No capability matches "<question>".

This might be a gap in the project. Options:

Use AskUserQuestion:

• "Search KB" — try /kb "<question>" for research that might be related
• "Check decisions" — try /decisions "<question>" for deferred work
• "Create capability" — start /capabilities add if this should exist
• "Done" — stop

capabilities list — browse all by domain

Read .capabilities/CLAUDE.md for the domain map. For each domain, read its CLAUDE.md index. Display:

───────────────────────────────────────────────
Project Capabilities (<n> total, <d> domains)
───────────────────────────────────────────────

<domain name> — <domain description>

  <title> (<type>) — <tags>
    <first sentence of "What it does">
    Features: <count> | Specs: <spec_refs> | Status: <status>

  <title> (<type>) — <tags>
    ...

<domain name> — <domain description>
  ...

───────────────────────────────────────────────

Refinement-type capabilities are displayed after core capabilities within their domain, visually indented or annotated. Emergent capabilities show their composes field.

capabilities add "" — create a new entry

Interactive creation of a capability entry.

Step 1 — Domain placement

Read .capabilities/CLAUDE.md for existing domains. Use AskUserQuestion:

• One option per existing domain
• "New domain" — create a new domain (prompt for name and description)

Step 2 — Capability type

Use AskUserQuestion:

• "Core" — primary user-visible capability
• "Emergent" — arises from composition of other capabilities
• "Refinement" — quality/performance improvement in this domain

Step 3 — Gather information

Description: "Describe this capability in 1-2 sentences. What can the user do?"

Tags: "What tags describe this capability? (comma-separated)" Suggest tags based on the name, description, and domain.

Status: Use AskUserQuestion:

• "Active" — capability is implemented and available
• "Planned" — capability is designed but not yet built
• "Deprecated" — capability is being phased out

Step 4 — Type-specific fields

For emergent capabilities: Read all domain indexes. Ask: "Which capabilities does this compose?" Use AskUserQuestion with multiSelect, listing capabilities from all domains. Require at least 2.

For refinement capabilities: Ask: "Which domain area does this refine?" (The answer is implicit from the domain placement, but confirm.)

Step 5 — Cross-reference discovery

Search existing artifacts for links:

1. Specs: Search .spec/registry/manifest.json (if exists) for domain keywords matching the capability name and tags
2. Decisions: Search .decisions/CLAUDE.md for ADR slugs matching keywords
3. KB: Search .kb/CLAUDE.md for topic/category matches
4. Features: Search .feature/ and .feature/_archive/ for feature slugs with matching brief descriptions

Present discovered cross-references and let the user confirm: "I found these potential links. Select which ones apply."

Use AskUserQuestion with multiSelect for each artifact type.

Step 6 — Feature descriptions and roles

If features were linked, for each feature ask:

1. One-line description of the feature's contribution
2. Role: Use AskUserQuestion:
   • "Core" — primary implementation of this capability
   • "Extends" — adds a new dimension
   • "Quality" — performance/cleanup improvement
   • "Enables" — prerequisite, but the capability is its own concern

Step 7 — Dependencies

Ask: "Does this capability depend on any other capabilities?"

Read domain indexes and present existing capabilities as options (using <domain>/<slug> format for cross-domain references).

Ask: "Does this capability enable any planned capabilities?"

Step 8 — Key behaviors

Ask: "What are the 3-8 key behaviors a user should know about? Link to spec requirements where possible (e.g., F03.R1)."

Step 9 — Write the entry

Write .capabilities/<domain>/<slug>.md with the gathered information following the entry template.

Update .capabilities/<domain>/CLAUDE.md — add a row to the Capabilities table.

Update .capabilities/CLAUDE.md — update domain capability count and add a row to Recently Updated.

Display:

Created capability: <title>
  Domain: <domain>
  Type: <type>
  Entry: .capabilities/<domain>/<slug>.md
  Tags: <tags>
  Links: <n> specs, <n> decisions, <n> KB topics, <n> features

capabilities update "" — update an existing entry

Find the entry by searching domain indexes for the slug. Read the existing entry. Present what's there and ask what to change.

Use AskUserQuestion:

• "Add features" — link new features to this capability (with role)
• "Update description" — revise the description or key behaviors
• "Update cross-references" — add/remove spec, ADR, KB, or dependency links
• "Change status" — active/planned/deprecated
• "Move domain" — move to a different domain

After changes, append an ## Updates <YYYY-MM-DD> section to the entry (following the KB pattern of never overwriting). Update the Recently Updated table in the root CLAUDE.md and the domain CLAUDE.md.

capabilities backfill — bootstrap from existing project artifacts

Scans existing features, specs, and ADRs to propose an initial set of domain-organized capabilities. Use this when adopting the capability index on a project that already has work done.

Step 1 — Gather existing artifacts

Read these sources (skip any that don't exist):

1. Feature briefs: .feature/_archive/*/brief.md and .feature/*/brief.md — extract feature name and description
2. Spec registry: .spec/registry/manifest.json — extract domain taxonomy and feature IDs
3. Confirmed ADRs: .decisions/CLAUDE.md — extract accepted decision slugs and their recommendation summaries
4. KB topics: .kb/CLAUDE.md — extract topic map for cross-reference

Step 2 — Detect existing flat capabilities

If .capabilities/CLAUDE.md exists and contains a flat Capability Map table (no Domain Map), this is a migration. Read existing entries and incorporate them into the domain proposal.

Step 3 — Propose domain groupings

Analyze the features, specs, and ADRs to identify logical domains:

1. Use the spec registry's domain taxonomy as the primary signal for domain boundaries (e.g., encryption, query, engine spec domains suggest capability domains)
2. Group features by the user-visible concern they serve — not by implementation coupling
3. Identify cross-cutting capabilities that compose multiple domains (candidates for emergent type)

Present proposed domains:

Backfill analysis suggests <n> capability domains:

  <domain name> — <description>
    Capabilities: <list>

  <domain name> — <description>
    ...

Use AskUserQuestion:

• "Accept domains" — proceed with these domains
• "Adjust" — modify domain names, merge, or split (describe changes)

Step 4 — Propose capabilities within domains

For each accepted domain, propose capabilities:

1. Group features that contribute to the same user-visible capability
2. Assign feature roles: core for primary implementation, extends for new dimensions, quality for performance/cleanup
3. Identify pre-existing capabilities implied by specs or ADRs that have no feature backing
4. Identify refinement candidates — capabilities where all features have quality role
5. Identify emergent candidates — capabilities that compose 2+ other capabilities from different domains

Present all proposals grouped by domain:

<domain name>:

  1. <capability name> (core) — <description>
     Features: <slug> (core), <slug> (quality)
     Specs: <refs>  ADRs: <refs>

  2. <capability name> (emergent) — <description>
     Composes: <capability A> + <capability B>

  ...

Use AskUserQuestion:

• "Create all" — create entries for all proposed capabilities
• "Select" — choose which ones to create
• "Review" — show full details before deciding

Step 5 — Create entries

For each accepted capability:

1. Create the domain directory and domain CLAUDE.md if it doesn't exist
2. Write the capability entry file with gathered data pre-filled
3. The user can adjust descriptions, tags, and cross-references before writing

Step 6 — Summary

Backfill complete:
  Domains: <n>
  Capabilities: <n> (<n> core, <n> emergent, <n> refinement)
  Features linked: <n>
  Specs linked: <n>
  ADRs linked: <n>

Run /capabilities list to see the full index.

Setup — seed template

When creating .capabilities/CLAUDE.md for the first time:

# Project Capabilities

> Managed by vallorcine agents. Use /capabilities to query.
> Pull model. Navigate: domain → capability file.
> Do not scan this directory recursively.
> Structure: .capabilities/<domain>/<capability>.md

## Domain Map

| Domain | Path | Capabilities | Last Updated |
|--------|------|-------------|--------------|

## Recently Updated (last 5)

| Date | Domain | Capability | Change |
|------|--------|-----------|--------|

Domain index template

When creating .capabilities/<domain>/CLAUDE.md:

# <Domain Name> — Capability Domain

> Pull model. Read capability files for details.

<1-2 sentence description of what this domain covers>

## Capabilities

| Capability | Type | Status | Tags | Features |
|-----------|------|--------|------|----------|

## Cross-references

- **KB topics:** <related KB topic paths>
- **Spec domains:** <related spec domain names>

Capability entry template

When writing a new .capabilities/<domain>/<slug>.md:

---
title: "<name>"
slug: "<slug>"
domain: <domain-slug>
status: <active | planned | deprecated>
type: <core | emergent | refinement>
tags: [<tags>]
features:
  - slug: <feature-slug>
    role: <core | extends | quality | enables>
    description: "<one-line contribution>"
composes: [<domain/capability slugs>]  # Only for type: emergent
spec_refs: [<spec IDs>]
decision_refs: [<ADR slugs>]
kb_refs: [<KB topic/category paths>]
depends_on: [<domain/capability slugs>]
enables: [<domain/capability slugs>]
---

# <title>

<2-5 sentences: what the user can do, what problem it solves>

## What it does

<expanded description>

## Features

<rendered from frontmatter features array, grouped by role>

## Key behaviors

- <behavior 1> (<spec ref if available>)
- <behavior 2>
...

## Related

- **Specs:** <list>
- **Decisions:** <list>
- **KB:** <list>
- **Depends on:** <list>
- **Enables:** <list>
- **Composes:** <list, only for emergent>
- **Deferred work:** <list of related deferred ADRs>