Help us improve
Share bugs, ideas, or general feedback.
From intent-layer
Query the Intent Layer to answer questions about the codebase. Use when asking "what owns X?", "where should I put Y?", "what constraints apply to Z?", or navigating an unfamiliar codebase using its AGENTS.md hierarchy.
npx claudepluginhub orban/intent-layer --plugin intent-layerHow this skill is triggered — by the user, by Claude, or both
Slash command
/intent-layer:intent-layer-queryThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Query an existing Intent Layer to answer architectural and navigation questions.
Scans a codebase, conducts a structured interview, and produces a shareable architecture insights document. Use when assessing codebase architecture or direction.
Persists codebase knowledge across sessions to avoid re-discovery. Use after exploration to record, before tasks to consult, or when dispatching subagents with module-specific context.
Builds and maintains ARCHITECTURE.md and DETAILED_DESIGN.md incrementally with coverage tracking. Principal mode analyzes vision, bottlenecks, gaps, and alternatives.
Share bugs, ideas, or general feedback.
Query an existing Intent Layer to answer architectural and navigation questions.
completeintent-layer skill first if state is none or partial# Check state first
${CLAUDE_PLUGIN_ROOT}/scripts/detect_state.sh /path/to/project
# View hierarchy
${CLAUDE_PLUGIN_ROOT}/scripts/show_hierarchy.sh /path/to/project
# Check health
${CLAUDE_PLUGIN_ROOT}/scripts/show_status.sh /path/to/project
"What owns X?" - Find responsible component for a concept.
Process:
Example:
Q: "What owns authentication?"
Search: grep -r "authentication\|auth" in CLAUDE.md/AGENTS.md files
Result: src/auth/AGENTS.md owns authentication
Parent: CLAUDE.md references auth as critical subsystem
Output format:
## Ownership: [concept]
**Primary owner:** `path/to/AGENTS.md`
> [TL;DR from that node]
**Parent context:** `CLAUDE.md`
> [Relevant excerpt about this area]
**Contracts:**
- [Any constraints from owner or ancestors]
"Where should I put X?" - Find correct location for new code.
Process:
Example:
Q: "Where should I put a new payment processor?"
Analysis:
- payments/ exists → check src/payments/AGENTS.md
- If AGENTS.md says "owns all payment logic" → put there
- If AGENTS.md says "only Stripe" → may need new sibling
Output format:
## Placement: [new thing]
**Recommended:** `path/to/directory/`
**Reason:** [Why this location based on Intent Layer]
**Relevant contracts:**
- [Constraints that apply to this location]
**Alternatives considered:**
- `other/path/` - rejected because [reason from Intent Layer]
"What constraints apply to X?" - Gather all rules for an area.
Process:
Example:
Q: "What constraints apply to the API layer?"
Walk: src/api/AGENTS.md → CLAUDE.md
Collect:
- From src/api/AGENTS.md: "All endpoints must validate auth token"
- From CLAUDE.md: "Never log PII", "Use structured logging"
Output format:
## Constraints: [area]
### From `path/to/specific/AGENTS.md`
- [Local constraints]
### Inherited from `CLAUDE.md`
- [Global constraints that apply]
### Effective rules (merged)
1. [Most important constraint]
2. [Second constraint]
...
"How do I [task]?" - Find starting point for common tasks.
Process:
Example:
Q: "How do I add a new API endpoint?"
Search Entry Points for: "API", "endpoint", "route"
Match: src/api/AGENTS.md → Entry Points → "Add endpoint: start at routes/"
Output format:
## Entry Point: [task]
**Start here:** `path/to/file.ts`
**From:** `path/to/AGENTS.md`
**Steps:**
1. [Step from Entry Points section]
2. [Additional context if available]
**Watch out for:**
- [Relevant pitfalls from same node]
"What can go wrong with X?" - Gather warnings for an area.
Process:
Output format:
## Pitfalls: [area]
### Critical (from nearest node)
- [Pitfall 1]
- [Pitfall 2]
### Inherited (from ancestors)
- [Global pitfall that applies]
### Related anti-patterns
- [Things to avoid]
"Why is X designed this way?" - Find rationale for decisions.
Process:
Output format:
## Architecture: [topic]
**Decision:** [What was decided]
**Rationale:** [Why, from Architecture Decisions section]
**Source:** `path/to/AGENTS.md` or linked ADR
**Related:**
- [Links to ADRs or design docs]
For complex queries, use this interactive process:
Classify the query:
# View full hierarchy
${CLAUDE_PLUGIN_ROOT}/scripts/show_hierarchy.sh /path/to/project
# Search for concept in Intent Nodes
grep -r "concept" --include="CLAUDE.md" --include="AGENTS.md" /path/to/project
For the relevant node:
Combine findings into the appropriate output format (see Query Types above).
Always include:
| Level | Meaning |
|---|---|
| Explicit | Directly stated in Intent Node |
| Inferred | Derived from multiple nodes |
| Uncertain | Not documented, using code analysis |
Always state confidence:
**Confidence:** Explicit (from src/auth/AGENTS.md:15)
or
**Confidence:** Inferred (no direct documentation, based on code structure)
**Recommendation:** Add to Intent Layer via maintenance skill
If the Intent Layer doesn't answer the question:
### Intent Layer Feedback
| Type | Location | Finding |
|------|----------|---------|
| Missing ownership | `CLAUDE.md` | No documented owner for [concept] |
Fall back to code analysis, but flag uncertainty:
## Answer (from code analysis)
**Confidence:** Uncertain - not documented in Intent Layer
[Answer based on code reading]
**Recommendation:** Document this in [suggested node]
If multiple gaps found, suggest running intent-layer-maintenance skill.
For Intent Layers with 5+ nodes or complex multi-faceted queries, use parallel subagents.
| Scenario | Approach |
|---|---|
| Single concept, small Intent Layer | Sequential search |
| Single concept, large Intent Layer (5+ nodes) | Parallel node search |
| Multi-faceted query (ownership + constraints + pitfalls) | Parallel aspect search |
| Cross-cutting concern investigation | Parallel subsystem search |
Search all nodes simultaneously for a concept:
Task 1 (Explore): "Search CLAUDE.md for references to [concept].
Return: any mentions, ownership claims, constraints, pitfalls"
Task 2 (Explore): "Search src/api/AGENTS.md for references to [concept].
Return: any mentions, ownership claims, constraints, pitfalls"
Task 3 (Explore): "Search src/core/AGENTS.md for references to [concept].
Return: any mentions, ownership claims, constraints, pitfalls"
Synthesis: Combine results, identify primary owner (most specific claim), collect all constraints.
For complex queries needing multiple perspectives:
Q: "What do I need to know to add a new payment provider?"
Task 1 (Explore): "Search Intent Layer for ownership of payments.
Who owns payment logic? What's in scope/out of scope?"
Task 2 (Explore): "Search Intent Layer for payment-related contracts.
What invariants apply? What patterns are required?"
Task 3 (Explore): "Search Intent Layer for payment-related pitfalls.
What surprises exist? What has broken before?"
Task 4 (Explore): "Search Intent Layer for payment entry points.
How do I add new payment functionality?"
Synthesis: Combine into comprehensive answer covering ownership, constraints, warnings, and starting point.
For concepts that span multiple subsystems:
Q: "How is authentication handled across the system?"
Task 1 (Explore): "Search src/api/AGENTS.md for auth mentions.
How does API layer handle auth?"
Task 2 (Explore): "Search src/core/AGENTS.md for auth mentions.
How does core layer handle auth?"
Task 3 (Explore): "Search src/db/AGENTS.md for auth mentions.
How does data layer handle auth?"
Synthesis: Map auth flow across subsystems, identify gaps in documentation.
| Query Type | Sequential | Parallel |
|---|---|---|
| Concept in 8 nodes | ~16 reads | ~3 reads (parallel) |
| Multi-aspect query | ~12 reads | ~4 reads (parallel) |
| Cross-cutting search | ~10 reads | ~3 reads (parallel) |
Query: "What constraints apply to the checkout flow?"
Parallel execution:
Task 1: "Find all constraints in src/checkout/AGENTS.md"
Task 2: "Find all constraints in src/payments/AGENTS.md"
Task 3: "Find all global constraints in CLAUDE.md that mention checkout, payment, or transaction"
Synthesis output:
## Constraints: checkout flow
### From `src/checkout/AGENTS.md`
- Cart must be validated before payment initiation
- Inventory reserved for 15 minutes during checkout
### From `src/payments/AGENTS.md`
- All payment calls must be idempotent
- Failed payments must not leave partial state
### Inherited from `CLAUDE.md`
- All financial operations must be logged
- PII never logged in plain text
### Effective rules (merged)
1. Validate cart → reserve inventory → initiate payment (order matters)
2. Payment calls must be idempotent
3. Log all operations, redact PII
4. 15-minute timeout on reservations
| Question Pattern | Query Type | Key Sections to Check |
|---|---|---|
| "What handles X?" | Ownership | TL;DR, Subsystem Boundaries |
| "Where does X live?" | Ownership | Subsystem Boundaries, Downlinks |
| "Where should I add X?" | Placement | Ownership + Out of Scope |
| "Can I do X here?" | Constraints | Contracts, Anti-patterns |
| "What rules apply to X?" | Constraints | Contracts (all ancestors) |
| "How do I X?" | Entry Point | Entry Points section |
| "What's dangerous about X?" | Pitfalls | Pitfalls, Anti-patterns |
| "Why X instead of Y?" | Architecture | Architecture Decisions |
This skill uses scripts from intent-layer:
| Script | Query Use |
|---|---|
show_hierarchy.sh | Visualize full Intent Layer structure |
show_status.sh | Check health before querying |
detect_state.sh | Verify Intent Layer exists |
All paths: ${CLAUDE_PLUGIN_ROOT}/scripts/
User: "What owns user sessions?"
Process:
grep -r "session" --include="*.md" in Intent Nodessrc/auth/AGENTS.md: "Owns: authentication, sessions, tokens"CLAUDE.md confirms: "Auth subsystem handles all identity"Answer:
## Ownership: user sessions
**Primary owner:** `src/auth/AGENTS.md`
> Owns authentication, session management, and token lifecycle.
**Contracts:**
- Sessions must expire after 24h inactivity
- Session tokens never logged
**Confidence:** Explicit (src/auth/AGENTS.md:23)
User: "Where should I add rate limiting?"
Process:
src/api/AGENTS.md owns "request pipeline"Answer:
## Placement: rate limiting
**Recommended:** `src/api/middleware/`
**Reason:** API layer owns request pipeline, rate limiting is request-level concern
**Constraints from Intent Layer:**
- Middleware must be stateless (use Redis for counters)
- All middleware must log to structured logger
**Confidence:** Inferred (no explicit mention, derived from ownership)
**Recommendation:** Add rate limiting to src/api/AGENTS.md Entry Points