C3 Query - Architecture Navigation

Navigate C3 docs AND explore corresponding code. Full context = docs + code.

Relationship to c3-navigator agent: This skill defines the query workflow. The c3-navigator agent implements this workflow. Use the agent when spawning via Task tool; use this skill directly for inline execution.

Precondition: C3 Adopted

Run npx -y @lagz0ne/c3x list --json via Bash. If it fails or returns empty, STOP.

If missing:

This project doesn't have C3 docs yet. Use the c3-onboard skill to create documentation first.

Do NOT proceed until topology is confirmed.

REQUIRED: Load References

Before proceeding, Read these files (relative to this skill's directory):

• references/skill-harness.md

• Red flags and complexity rules

• references/layer-navigation.md

• How to traverse C3 docs

• references/constraint-chain.md

• Constraint chain query procedure (for "what constraints apply to X")

Query Flow

Query → Load Topology (CLI) → Clarify Intent → Navigate Layers → Extract References → Explore Code │ └── Use AskUserQuestion if ambiguous

Progress Checklist

Query Progress:

• Step 0a: Topology loaded via npx -y @lagz0ne/c3x list --json
• Step 0b: Intent clarified (or skipped if specific)
• Step 1: Context navigated (found relevant container/component from JSON)
• Step 2: References extracted (code paths, symbols — Read docs for body content)
• Step 3: Code explored (verified against docs)
• Response delivered with layer, refs, insights

Step 0a: Load Topology

FIRST action: Run npx -y @lagz0ne/c3x list --json via Bash to load full topology.

npx -y @lagz0ne/c3x list --json

The JSON output contains every entity's id, type, title, path, relationships, and frontmatter. Use this to:

• Identify which containers, components, refs, and ADRs exist

• Match the user's query to relevant entities by title, type, or relationship

• Resolve C3 IDs (c3-N, c3-NNN, adr-, ref-) to file paths

Do NOT manually Glob or Read .c3/ directory listings. The JSON has everything needed for discovery.

Only use the Read tool after you've identified specific entities from the JSON — and only when you need body content (prose, Code References sections, edge cases) that isn't in the frontmatter.

Step 0b: Clarify Intent

Ask when:

• Query vague ("how does X work?" - which aspect?)

• Multiple interpretations ("authentication" - login? tokens? sessions?)

• Scope unclear ("frontend" - whole container or specific component?)

Skip when:

• Query includes C3 ID (c3-102)

• Query specific ("where is login form submitted?")

• User says "show me everything about X"

Step 1: Navigate Layers

Use the JSON topology from Step 0a to navigate: Context → Container → Component

• Match from JSON — Find relevant entities by title, type, or relationships in the JSON output

• Read for depth — Only Read entity files when you need body content (prose, ## Code References , edge cases) not available in the JSON frontmatter

Doc Section Extract For Code

Component name Class/module names

Code References

Direct file paths, symbols

Technology Framework patterns

Entry points Main files, handlers

Step 2: Extract References

From the identified component(s), extract:

• File paths from ## Code References

• Related patterns from ## Related Refs

Reference Lookup

If query relates to patterns/conventions:

• Find matching ref-* entities from the JSON topology (loaded in Step 0a)

• Read ref file for body content, return ref content + citing components

Step 3: Explore Code

Use extracted references:

• Glob: src/auth/**/*.ts

• Grep: Class names, functions

• Read: Specific files from ## Code References

Query Types

Type User Says Response

Docs "where is X", "explain X" Docs + suggest code exploration

Code "show me code for X" Full flow through code

Deep "explore X thoroughly" Docs + Code + Related

Constraints "what rules/constraints apply to X" Full constraint chain

Constraint Chain Query

For constraint queries ("what constraints apply to X?"), follow the procedure in references/constraint-chain.md . Read upward through the hierarchy, collect cited refs, and synthesize the full constraint chain.

Edge Cases

Situation Action

Topic not in C3 docs Search code directly, suggest documenting if significant

Spans multiple containers List all affected containers, explain relationships

Docs seem stale Note discrepancy, suggest running c3-audit or c3-change skill to fix

Examples

Example 1: Component lookup

User: "Where is authentication handled?"

Step 0a: Run npx -y @lagz0ne/c3x list --json → JSON shows c3-2-api container, c3-201-auth-middleware component with title "Auth Middleware" Step 1: Match "authentication" → c3-201-auth-middleware (from JSON relationships + title) Step 2: Read .c3/c3-2-api/c3-201-auth-middleware.md → Get code refs (need body content)

Response: Layer: c3-201 (Auth Middleware)

Authentication is handled by the AuthMiddleware component in the API container.

Code References:

• src/api/middleware/auth.ts - JWT validation
• src/api/middleware/session.ts - Session management

Key Insights: Uses RS256 for JWT signing. Sessions stored in Redis.

Related: See c3-202-user-service for user lookup

Example 2: Pattern lookup

User: "How does error handling work?"

Step 0a: Run npx -y @lagz0ne/c3x list --json → JSON shows ref-error-handling entity, cited by c3-201, c3-203, c3-205 Step 1: Match "error handling" → ref-error-handling (from JSON title + relationships)

Response: Pattern: ref-error-handling

Error handling follows a centralized pattern documented in refs.

Pattern Summary:

• All errors extend BaseError class
• HTTP errors map to status codes via errorToStatus()
• Logged with correlation ID

Used By: c3-201, c3-203, c3-205

Response Format

Layer: <c3-id> (<name>)

<Architecture from docs>

Code References:

• path/file.ts - <role>

Key Insights: <Observations from code>

Related: <navigation hints>

For constraint chain queries, use the response format in references/constraint-chain.md instead.