feat(skills): unify ask, impact, trace into query skill and integrate cypher

AGENT.md

@@ -0,0 +1,14 @@
+# AGENT.md
+
+This file contains instructions and project-specific rules for AI agents (e.g., Claude Code).
+
+## Project Overview
+`docgraph` is a tool for validating and managing graph structures within Markdown files.
+
+## Skills
+Project-specific skills are defined in `.claude/skills` (linked from `.agent/skills`). Please use them proactively.
+Specifically, use the `query` skill for all graph exploration, impact analysis, and traceability checks.
+
+## Rules
+- Respond in Japanese.
+- Use **conventional commits** for commit messages, written in **English**.

CLAUDE.md

@@ -0,0 +1 @@
+AGENT.md

docgraph-plugin/skills/align/SKILL.md

@@ -22,11 +22,12 @@ context (Vertical) and their peers (Horizontal).
 
 ## Workflow Steps
 
-### 0. Validation Pre-requisite
+### 0. Structural & Validation Pre-requisite
 
 - **Level**: STRICT
 - **Policy**:
-  - If `validate` status is unknown or FAIL -> **STOP** and return FAIL.
+  1. **Schema Context**: Read `docgraph.toml` to understand the valid node types and relationship rules for the target scope.
+  2. **Validation Status**: If `validate` status is unknown or FAIL -> **STOP** and return FAIL.
   - Do not re-evaluate surface items (naming, templates) already covered by `validate`.
 
 ### 1. Vertical Consistency (Traceability & Context)
@@ -37,7 +38,7 @@ context (Vertical) and their peers (Horizontal).
   - **This Node**: Defines the "What" at its specific abstraction level.
   - **Children (Outbound)**: Define the "How" (realization, implementation, or breakdown).
 
-1. **Context Check**: Use `docgraph describe <ID>` and verify:
+1. **Context Check**: Use `docgraph describe <ID>` or `docgraph query` and verify:
    - Does the parent node explicitly justify the existence of this node?
    - Is there any gap in how the parent's intent is carried over?
 2. **Realization Check**: Verify child nodes:
@@ -49,7 +50,8 @@ context (Vertical) and their peers (Horizontal).
 - **Baseline Rule**: Use the dominant pattern among existing peer nodes. Do not invent new abstraction levels unless
   proposing an explicit refactor.
 
-1. **Peer Identification**: Use `docgraph list "<PREFIX>_*"`.
+1. **Peer Identification**: Use `docgraph query`.
+   - Example: `docgraph query "MATCH (n:FR) WHERE n.id STARTS WITH 'FR_AUTH' RETURN n.id"`
 2. **Overlap Check**: Verify Mutually Exclusive and Collectively Exhaustive (MECE) status.
    - Does this node's responsibility overlap with peer nodes?
    - Is the granularity consistent with the peer baseline?

docgraph-plugin/skills/query/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: query
+description: Documentation Graph Query & Analysis - Explore, investigate, and assess the graph using semantic tools and Cypher.
+---
+
+# Documentation Graph Query & Analysis
+
+This skill provides a unified methodology for exploring the documentation graph, answering specific questions, and
+analyzing the impact or traceability of specifications. It leverages `docgraph` specific tools to navigate the semantic
+structure of the graph.
+
+> [!TIP] Use this skill for any graph-related investigation: from finding a requirement to analyzing the ripple effect
+> of a change or verifying that an intent is fully realized.
+
+## Prerequisites
+
+- **`docgraph` CLI must be installed as a system binary**
+  - Install via: `curl -fsSL https://raw.githubusercontent.com/sonesuke/docgraph/main/install.sh | bash`
+  - Or build from source: `cargo install --path .`
+- **Installation Verification**: Run `docgraph --version` to confirm the binary is available
+
+## Tools & Techniques
+
+### 0. Structural Understanding (Phase 0)
+
+Before executing any query, you **MUST** understand the project's graph schema.
+- **Action**: Read `docgraph.toml` in the project root.
+- **Objective**: Identify supported node types (`UC`, `FR`, `MOD`, etc.), their relationship rules (`dir`, `targets`), and their associated templates.
+
+### 1. `docgraph query` (Powerful Search)
+
+Uses Cypher-like syntax for precise, attribute-aware, and relational searching. **This is the preferred tool for complex
+searches.**
+
+- **Usage**: `docgraph query "<CYPHER_QUERY>"`
+- **Capabilities & Examples**:
+  - **Basic Discovery**: `docgraph query "MATCH (n:FR) RETURN n.id"` - List all nodes of a specific type.
+  - **Attribute Filtering**: `docgraph query "MATCH (n) WHERE n.name CONTAINS 'Auth' RETURN n.id, n.name"` - Search by properties.
+  - **Path Traversal**: `docgraph query "MATCH (fr:FR)-[*1..2]->(uc:UC) WHERE uc.id = 'UC_001' RETURN fr.id"` - Trace multi-hop relationships.
+  - **Relationship Semantics**: Use `docgraph.toml` context labels for filtering or reasoning.
+    - `docgraph query "MATCH (u:UC)-[r:uses]->(f:FR) RETURN f.id, r.type"` - Filter by relationship type and retrieve its label.
+    - `docgraph query "MATCH (n)-[r]->(m) WHERE r.type CONTAINS 'implements' RETURN n.id, m.id"` - Semantic filtering.
+
+### 2. `docgraph describe` (Exploration)
+
+Deep dive into a single node's content and immediate relations. `docgraph describe <ID>`
+- _Benefit_: Use this to see direct inbound/outbound links and the local "Why/How" context.
+
+### 3. `docgraph trace` (Lineage & Realization)
+
+Follow chains of relationships to verify traceability or global impact.
+
+- **Usage**: `docgraph trace <START_ID> --direction <up|down>`
+- **Realization Check (Down)**: Verify if an abstract intent (FR) reaches a terminal implementation (MOD, IF).
+- **Justification Check (Up)**: Verify the origin/intent of a low-level specification.
+
+---
+
+## Workflow: Impact Analysis
+
+Use this workflow before renaming IDs, moving files, or changing core requirement logic.
+
+1. **Local Impact**: Use `docgraph describe <ID>` to list direct relations.
+2. **Global Ripple**: Use `docgraph trace <ID> --direction down` (to see what is broken downstream) and `--direction up`
+   (to see what loses its justification upstream).
+3. **Cross-Cutting**: Search for related concepts using `docgraph query` or `grep`.
+4. **Report**: List affected IDs and categorize impact level (HIGH/MED/LOW).
+
+## Workflow: Traceability Verification
+
+Use this workflow to ensure a node’s responsibility is fully traceable and ultimately realizable.
+
+1. **Downstream Traversal**: Use `trace <ID> --direction down`.
+2. **Terminal Reachability**: Ensure at least one path reaches a realizable terminal (MOD, IF, CODE).
+3. **Abstraction Monotonicity**: Ensure abstraction decreases (FR > UC > MOD > CODE).
+4. **Semantic Continuity**: Verify that the core intent survives through the transitions without "semantic fog" or
+   drift.
+
+---
+
+## Query & Analysis Report
+
+Structure your findings to provide clear insights:
+
+### Findings Summary
+- **Scope/Target**: [ID or Query]
+- **Key Relationships Found**: [e.g., "FR_001 realized by MOD_AUTH"]
+- **Impact/Traceability Result**: [PASS/FAIL or Risk Level]
+
+### Detailed Analysis
+Provide the detailed answer or assessment built from the gathered context.
+
+### Navigation Trace (optional)
+`FR_001` -> `IF_001` -> `MOD_001`