iurykrieger/claude-bedrock/ask

/bedrock:ask — Adaptive Vault Reader

Plugin Paths

Entity definitions and templates are in the plugin directory, not at the vault root. Use the "Base directory for this skill" provided at invocation to resolve the paths:

• Entity definitions: <base_dir>/../../entities/
• Templates: <base_dir>/../../templates/{type}/_template.md
• Plugin CLAUDE.md: <base_dir>/../../CLAUDE.md (already automatically injected into context)

Where <base_dir> is the path provided in "Base directory for this skill".

Vault Resolution

Resolve which vault to query. This skill can be invoked from any directory.

Step 1 — Parse `--vault` flag: Check if the input arguments include --vault <name>. If found, extract the vault name and remove it from the arguments (the remaining text is the question).

Step 2 — Resolve vault path:

1. If `--vault <name>` was provided:

Read the vault registry at <base_dir>/../../vaults.json. Find the entry matching the name. If not found: error — "Vault <name> is not registered. Run /bedrock:vaults to see available vaults." If found: set VAULT_PATH to the entry's path value.

1. If no `--vault` flag — CWD detection:

Read <base_dir>/../../vaults.json. Check if the current working directory is inside any registered vault path (CWD starts with a registered vault's absolute path). If multiple match, use the longest path (most specific). If found: set VAULT_PATH to the matching vault's path.

1. If CWD detection fails — default vault:

From the registry, find the vault with "default": true. If found: set VAULT_PATH to the default vault's path.

1. If no resolution:

Error — "No vault resolved. Available vaults:" followed by the registry listing. "Use --vault <name> to specify, or run /bedrock:setup to register a vault."

Step 3 — Validate vault path:

test -d "<VAULT_PATH>" && echo "exists" || echo "missing"

If missing: error — "Vault path <VAULT_PATH> does not exist on disk. Run /bedrock:setup to re-register."

Step 4 — Read vault config:

cat <VAULT_PATH>/.bedrock/config.json 2>/dev/null

Extract language and other relevant fields for use in later phases.

From this point forward, ALL vault file operations use `<VAULT_PATH>` as the root.

• Entity directories: <VAULT_PATH>/actors/, <VAULT_PATH>/people/, etc.
• Graphify output: <VAULT_PATH>/graphify-out/

Overview

This skill receives a natural language question and answers it using an adaptive, vault-first approach. It always reads vault content first, then decides whether to escalate to graphify or /learn ased on what's actually needed — not what the question looks like in isolation.

You are an adaptive context orchestrator agent. You only READ — never write, edit, or delete files directly.

Writes happen exclusively through /bedrock:learn delegation (which flows through /bedrock:preserve). If the query reveals outdated or missing information and no remote source is available to ingest, suggest that the user run /bedrock:preserve or /bedrock:learn to update the vault.

Phase 0 — Read Configuration

0.1 Load config

Read .bedrock/config.json from the vault root:

if [ -f ".bedrock/config.json" ]; then
    cat .bedrock/config.json
else
    echo "config_not_found"
fi

• If config exists: extract the value of query.max_graphify_calls. Store as max_graphify_calls.
• If config does not exist or field is absent: set max_graphify_calls = 3 (default).
• Valid range: 1–5. If the value is outside this range, clamp to the nearest bound and log a warning.

Phase 1 — Analyze the Question

1.1 Classify the question

Read the user's question and identify:

1. Mentioned entities — names of systems, people, teams, topics, projects, or discussions.

They may appear as:

• Exact filename (e.g.: "billing-api", "squad-payments")
• Human-readable name (e.g.: "Billing API", "Squad Payments")
• Alias or acronym (e.g.: "BillingAPI", "BRB")
• Contextual reference (e.g.: "the billing service", "the notifications team")

1. Relevant domain(s) — payments, notifications, orders, integrations, checkout, compliance, internal-tools.

Infer from the mentioned entities or the question context.

1. Type of information sought:

• Status/overview — "what is X?", "what's the status of X?"
• Architecture/stack — "how does X work?", "what's the stack of X?"
• People/teams — "who owns X?", "who works with Y?"
• History/decisions — "what was decided about X?", "what happened with Y?"
• Relationships — "what depends on X?", "how does Y relate to Z?"
• Deprecation — "what is being deprecated?", "what's the deprecation plan for X?"

1.2 Assess clarity

If the question is too ambiguous to produce a targeted search (e.g.: "tell me everything", "how does the system work?", "what's going on?"), ask for clarification:

"Your question is broad. Can you specify: which system, team, or topic would you like to know more about?"

If the question mentions something that clearly isn't part of the vault (e.g.: something personal, unrelated technology), inform: "I didn't find anything in the vault about this."

1.3 Phase 1 classification result

At the end, you should have:

• search_terms: list of names, aliases, and keywords to search for
• domains: list of relevant domains (may be empty if not identified)
• info_type: classification of the type of information sought
• explicit_entities: entities mentioned directly by name (if any)

Phase 2 — Graph-First Search

This phase always runs for every question. It uses the cumulative knowledge graph as the primary index when available, falling back to glob/grep for terms not represented in the graph. Never skip this phase.

2.0 Check graph.json and score nodes

Before any glob/grep, check if the cumulative knowledge graph is available:

if [ -f "<VAULT_PATH>/graphify-out/graph.json" ] && [ -s "<VAULT_PATH>/graphify-out/graph.json" ]; then
    echo "graph_available"
else
    echo "graph_not_available"
fi

If `graph_available`:

1. Read <VAULT_PATH>/graphify-out/graph.json — extract only the nodes array (skip edges to avoid context explosion on large graphs). If the nodes array exceeds 500 entries, read only the first 500 — graphify orders nodes by centrality, so high-value nodes come first.

1. From the nodes array, extract per node: id, label, file_type, source_file, community, is_god_node.

1. Score nodes by relevance to the search terms from Phase 1:

• Primary signal: node label contains or closely matches any search term
• Secondary signal: node belongs to a community that contains other high-scoring nodes (community resonance)
• Boost: is_god_node: true nodes get elevated priority when their label is even loosely relevant to the query

1. Select top N nodes (N ≤ 15, same limit as the current entity read budget). Track which search terms produced ≥ 1 matching node and which produced none.

1. For each selected node with a non-null source_file:

• Resolve the corresponding vault .md file: search for the source_file basename in entity directories

`` Glob: <VAULT_PATH>/actors/<basename>.md, <VAULT_PATH>/people/<basename>.md, <VAULT_PATH>/teams/<basename>.md, <VAULT_PATH>/topics/*<basename>*.md, <VAULT_PATH>/discussions/*<basename>*.md, <VAULT_PATH>/projects/<basename>.md ``

• If found: read the full entity file — this node is fully resolved (skip steps 2.2–2.4 for this entity)
• If not found: record graph metadata only (label, community, relevant edge labels) — use this metadata in Phase 5 response to surface the concept even without a vault file

1. For each search term that produced zero matching graph nodes → proceed to steps 2.2–2.4 (glob/grep) for that term only.

If `graph_not_available`: Skip to step 2.1. No warning — this is the normal path for fresh vaults.

2.1 Read entity definitions

Use Read to read the entity definition files from the plugin (see "Plugin Paths" section):

• If the question is about a system → read <base_dir>/../../entities/actor.md
• If the question is about a person → read <base_dir>/../../entities/person.md
• If the question is about a team → read <base_dir>/../../entities/team.md
• If the question is about a topic/deprecation → read <base_dir>/../../entities/topic.md
• If the question is about a meeting/decision → read <base_dir>/../../entities/discussion.md
• If the question is about a project/initiative → read <base_dir>/../../entities/project.md
• If you don't know the type → read all entity definitions from the plugin to classify correctly

2.2 Search entities by name and alias

For each search term identified in Phase 1:

Step 1 — Search by filename:

Glob: <VAULT_PATH>/actors/<term>*.md, <VAULT_PATH>/people/<term>*.md, <VAULT_PATH>/teams/<term>*.md,
      <VAULT_PATH>/topics/*<term>*.md, <VAULT_PATH>/discussions/*<term>*.md, <VAULT_PATH>/projects/<term>*.md,
      <VAULT_PATH>/fleeting/*<term>*.md

Step 2 — Search by alias in frontmatter:

Grep: pattern="aliases:.*<term>" in directories: <VAULT_PATH>/actors/, <VAULT_PATH>/people/, <VAULT_PATH>/teams/,
      <VAULT_PATH>/topics/, <VAULT_PATH>/discussions/, <VAULT_PATH>/projects/
      (case-insensitive)

Step 3 — Search by name in frontmatter:

Grep: pattern="name:.*<term>" or pattern="title:.*<term>"
      in the same directories (case-insensitive)

Step 4 — Search by content (fallback): If steps 1-3 did not return sufficient results:

Grep: pattern="<term>" in entity directories (case-insensitive)

2.3 Filter by domain

If domains were identified in Phase 1, filter results:

Grep: pattern="domain/<domain>" in the found files (tags field of frontmatter)

Keep all results, but prioritize those matching the domain.

2.4 Read found entities

For each entity found (limit: 15 entities):

1. Read the frontmatter first (~first 30 lines) to confirm relevance
2. If relevant: read the full file
3. If not relevant (false positive from Grep): discard

Record for each entity read:

• filename, type, name
• wikilinks found in frontmatter and body
• external URLs found in the content (Confluence, Google Docs, GitHub)
• Explicit date in the filename (if any)

2.5 Follow wikilinks (1 level of depth)

For each extracted wikilink that is relevant to the question:

1. Resolve the file: search for <wikilink-name>.md in entity directories

`` Glob: <VAULT_PATH>/actors/<name>.md, <VAULT_PATH>/people/<name>.md, <VAULT_PATH>/teams/<name>.md, <VAULT_PATH>/topics/*<name>*.md, <VAULT_PATH>/discussions/*<name>*.md, <VAULT_PATH>/projects/<name>.md ``

1. Read the found file (frontmatter + body)

1. Do NOT follow wikilinks from this second level — stop here to avoid context explosion

Relevance criteria for following a wikilink:

• The question is about relationships ("who owns", "what depends on") → follow all
• The question is about status/overview → follow team, people (focal points)
• The question is about history → follow related discussions, topics
• The question is about architecture → follow dependent actors

Limit: Do not read more than 15 entities total (2.4 + 2.5 combined). If the limit is reached, prioritize entities directly mentioned in the question.

2.6 Phase 2 output