LLM Navigation Guide¶

For AI Assistants: This guide helps you efficiently navigate the SyRF three-repository structure and assist users effectively.

Critical Context¶

Multi-Repository LLM-First Design¶

The SyRF project uses a deliberately designed multi-repository structure optimized for LLM visibility:

/home/chris/workspace/syrf/          # Working directory root
├── .git/                             # syrf main repository
├── CLAUDE.md                         # YOUR PRIMARY CONTEXT FILE
├── README.md                         # Project overview
├── docs/                             # Primary documentation hub
├── src/                              # Application code
├── cluster-gitops/                   # Nested repo (gitignored)
│   ├── .git/
│   └── docs/                         # Deployment operations
└── camarades-infrastructure/         # Nested repo (gitignored)
    ├── .git/
    └── docs/                         # Infrastructure operations

Key Insight: All three repositories are visible in a single workspace. You can read files from any repository without context switching.

Reading Strategy¶

Priority 1: Context Files (Read First)¶

When starting any task, always read these files first to understand current context:

/home/chris/workspace/syrf/CLAUDE.md (900+ lines)
LLM-specific instructions
Project structure and conventions
GitOps workflow rules
Critical "never do" warnings
Recent updates and deployment status
/home/chris/workspace/syrf/docs/README.md (1000+ lines)
Documentation framework guide
Document types and templates
YAML frontmatter structure
Lifecycle management
Validation rules
/home/chris/workspace/syrf/README.md (200+ lines)
Project overview
Key technologies
Repository structure
Quick start guide

Priority 2: Task-Specific Context¶

Based on the user's request, read relevant documentation:

Task Type	Read These Files
Feature Planning	docs/how-to/feature-planning-workflow.md docs/planning/templates/qa-template.md
Deployment	cluster-gitops/docs/deploying-services.md cluster-gitops/docs/promotion-workflow.md
Architecture Decision	docs/decisions/ADR-*.md (scan existing ADRs)
Service Development	docs/architecture/dependency-map.md src/services/{service}/README.md
Infrastructure	camarades-infrastructure/docs/terraform-guide.md

Priority 3: Discovery Tools¶

Use these tools for exploratory research:

Glob - Find files by pattern:

# All documentation
Glob: pattern="**/docs/**/*.md"

# Specific service
Glob: pattern="src/services/api/**/*.cs"

# Helm charts
Glob: pattern="**/charts/**/values.yaml"

Grep - Search content:

# Find documentation by type
Grep: pattern='doc-type: "ADR"' path="/home/chris/workspace/syrf/docs"

# Find draft documents
Grep: pattern='status: "Draft"' path="/home/chris/workspace/syrf/docs"

# Search for specific functionality
Grep: pattern="authentication" path="/home/chris/workspace/syrf/src"

YAML Front Matter Parsing¶

All documentation uses YAML frontmatter for metadata. Always parse this to understand document context:

---
doc-type: "Feature" | "Technical" | "ADR" | "How-To" | "Reference" | "Discussion"
status: "Draft" | "In-Review" | "Approved" | "Completed" | "Deprecated"
author: "Name"
created: YYYY-MM-DD
updated: YYYY-MM-DD
zenhub-ticket: "#123" | "TBD" | "N/A"
tags: ["tag1", "tag2"]
---

Use Grep to filter by metadata:

# Find all feature briefs
Grep: pattern='doc-type: "Feature"' path="/home/chris/workspace/syrf/docs/features"

# Find in-review documents
Grep: pattern='status: "In-Review"' path="/home/chris/workspace/syrf/docs"

# Find docs linked to specific ticket
Grep: pattern='zenhub-ticket: "#2128"' path="/home/chris/workspace/syrf/docs"

Quick Decision Trees¶

Where Do I Find Deployment Instructions?¶

Is it about...
├─ How to deploy applications?
│   → cluster-gitops/docs/deploying-services.md
├─ How to promote to production?
│   → cluster-gitops/docs/promotion-workflow.md
├─ What Helm values are available?
│   → src/services/{service}/charts/{chart}/values.yaml
├─ ArgoCD troubleshooting?
│   → cluster-gitops/docs/ (check index)
└─ Infrastructure changes?
    → camarades-infrastructure/docs/terraform-guide.md

Where Do I Document Changes?¶

Did you change...
├─ Application code?
│   → Update src/services/{service}/README.md
│   → Or create feature doc in docs/features/
├─ Helm chart?
│   → Update src/services/{service}/charts/README.md
├─ ArgoCD app manifest?
│   → Update cluster-gitops/docs/ if process changes
├─ Terraform?
│   → Update camarades-infrastructure/docs/ if procedure changes
├─ Architecture?
│   → Create ADR in docs/decisions/
└─ Team workflow?
    → Update docs/team.md or docs/README.md

Where Do I Place External Research?¶

Research type...
├─ Temporary / Unprocessed
│   → docs/sources/ (staging area)
│   → Will be incorporated into structured docs later
├─ Permanent Reference
│   → Create proper doc in docs/architecture/
│   → Use doc-type: "Reference"
└─ Feature-Specific
    → Include in Feature Brief or Technical Plan
    → Link to external sources

Cross-Repository Link Handling¶

Documentation uses full GitHub URLs for cross-repo links. Convert these to local paths when reading:

GitHub URL (in docs):

https://github.com/camaradesuk/cluster-gitops/blob/master/docs/deploying-services.md

Local Path (for Read tool):

/home/chris/workspace/syrf/cluster-gitops/docs/deploying-services.md

Pattern:

Replace https://github.com/camaradesuk/cluster-gitops/blob/master/ with /home/chris/workspace/syrf/cluster-gitops/
Replace https://github.com/camaradesuk/camarades-infrastructure/blob/master/ with /home/chris/workspace/syrf/camarades-infrastructure/

Common Task Patterns¶

Task: Plan a New Feature¶

Workflow:

Read docs/how-to/feature-planning-workflow.md
Check docs/sources/ for any external research
Use docs/planning/templates/qa-template.md to start Q&A
Conduct 3 iterations: Discovery → Requirements → Technical
Create Feature Brief in docs/features/{feature-name}/
Create Technical Plan alongside

Files to Create:

docs/features/{feature-name}/
├── README.md          # Feature Brief
└── technical-plan.md  # Technical Plan

YAML Frontmatter:

---
doc-type: "Feature"  # For Feature Brief
status: "Draft"
author: "{User Name}"
created: YYYY-MM-DD
updated: YYYY-MM-DD
zenhub-ticket: "TBD"
tags: ["{feature-name}", "planning"]
---

Task: Make an Architectural Decision¶

Workflow:

Grep for related ADRs: Grep: pattern="authentication" path="/home/chris/workspace/syrf/docs/decisions"
Read related ADRs to understand context
Create new ADR in docs/decisions/ADR-{number}-{title}.md
Follow ADR template from docs/README.md

ADR Structure:

---
doc-type: "ADR"
status: "Draft"
author: "{User Name}"
created: YYYY-MM-DD
updated: YYYY-MM-DD
zenhub-ticket: "N/A"
tags: ["architecture", "decision"]
---

# ADR-{number}: {Title}

## Status
Draft | Approved | Superseded

## Context
[What's the issue we're facing?]

## Decision
[What did we decide?]

## Consequences
[What are the results of this decision?]

Task: Deploy a Service¶

Workflow:

Read cluster-gitops/docs/deploying-services.md
Check service Helm chart: src/services/{service}/charts/{chart}/
Verify environment values: cluster-gitops/environments/{env}/{service}/
NEVER use kubectl apply - Use GitOps only
Update values in cluster-gitops repo
ArgoCD auto-syncs

Critical Rule (from CLAUDE.md):

NEVER USE kubectl apply OR helm install
↓
ALWAYS USE GitOps (commit to cluster-gitops)
↓
Let ArgoCD sync automatically

Task: Update Documentation¶

Workflow:

Identify document type and location
Read existing document
Edit with proper YAML frontmatter updates
Update updated: YYYY-MM-DD field
If status changes, update status field
Run validation: ./docs/scripts/validate-docs.sh

Status Lifecycle:

Draft → In-Review → Approved → Completed → Deprecated

GitHub MCP Integration¶

The project has GitHub MCP configured. Use these functions for automation:

Issue Management¶

// Create issue
mcp__github__issue_write({
  method: "create",
  owner: "camaradesuk",
  repo: "syrf",
  title: "Feature: User Authentication",
  body: "Description...",
  labels: ["feature", "planning"]
})

// Update issue
mcp__github__issue_write({
  method: "update",
  issue_number: 2128,
  state: "closed"
})

// Create sub-issue relationship
mcp__github__sub_issue_write({
  method: "add",
  parent_issue: 2128,
  child_issue: 2129
})

Search & Discovery¶

// Search issues
mcp__github__search_issues({
  query: "label:feature state:open",
  owner: "camaradesuk",
  repo: "syrf"
})

// Search code
mcp__github__search_code({
  query: "authentication language:csharp repo:camaradesuk/syrf"
})

Specialized Skills¶

The project has custom Claude skills in .claude/skills/:

docs-lifecycle-manager - Document validation and lifecycle
gitops-deployment-guide - GitOps workflow guidance
gitversion-calculator - Version calculation
monorepo-dependency-analyzer - Dependency analysis

Invoke skills when appropriate for specialized tasks.

Critical Rules (from CLAUDE.md)¶

GitOps Workflow - NEVER VIOLATE¶

❌ WRONG: kubectl apply -f ingress.yaml
❌ WRONG: helm install my-app ./chart
❌ WRONG: kubectl patch deployment ...

✅ CORRECT: Edit YAML in cluster-gitops repo → Commit → Push → ArgoCD syncs

DNS Management - NEVER VIOLATE¶

❌ WRONG: gcloud dns record-sets update argocd.camarades.net
✅ CORRECT: Let external-dns manage DNS automatically via Kubernetes Ingress

Documentation Management¶

❌ WRONG: Delete cluster-gitops/ or camarades-infrastructure/ directories
❌ WRONG: Guess file paths - always verify with Read or Glob first
❌ WRONG: Skip YAML frontmatter validation

✅ CORRECT: Ask before deleting directories
✅ CORRECT: Validate file paths exist
✅ CORRECT: Always include proper YAML frontmatter

File Path Reference¶

Absolute Paths (Use These)¶

All paths should be absolute starting from workspace root:

/home/chris/workspace/syrf/CLAUDE.md
/home/chris/workspace/syrf/docs/README.md
/home/chris/workspace/syrf/src/services/api/
/home/chris/workspace/syrf/cluster-gitops/docs/
/home/chris/workspace/syrf/camarades-infrastructure/terraform/

Relative Paths (For Documentation Links)¶

In markdown files, use relative paths:

# From docs/architecture/llm-navigation-guide.md
[Feature Planning](../how-to/feature-planning-workflow.md)
[CLAUDE.md](../../CLAUDE.md)

Verification Checklist¶

Before completing any task, verify:

Read CLAUDE.md for context
Followed GitOps workflow (no kubectl apply)
Updated YAML frontmatter (updated date, status)
Created docs in correct repository
Used absolute paths for file operations
Validated documentation (if docs changed)
Checked for related ADRs (if architectural)
Updated cross-references (if structure changed)

Quick Reference Tables¶

Document Types¶

doc-type	Purpose	Location
Feature	Feature briefs	docs/features/
Technical	Technical plans	docs/features/ (with Feature Brief)
ADR	Architecture decisions	docs/decisions/
How-To	Step-by-step guides	docs/how-to/
Reference	Permanent reference	docs/architecture/
Discussion	Temporary Q&A, proposals	docs/planning/

Status Values¶

Status	Meaning	Next Status
Draft	Work in progress	In-Review
In-Review	Under team review	Approved
Approved	Approved for implementation	Completed
Completed	Implementation finished	N/A
Deprecated	Superseded or obsolete	N/A

ZenHub Ticket Values¶

Value	Meaning
TBD	Not yet created in ZenHub
#123	Linked to Epic/Issue #123
N/A	No ZenHub ticket (reference docs, ADRs)

Performance Optimization¶

Read Strategy¶

Efficient:

// Read multiple files in parallel
Read: /home/chris/workspace/syrf/CLAUDE.md
Read: /home/chris/workspace/syrf/docs/README.md
Read: /home/chris/workspace/syrf/docs/architecture/dependency-map.md

Inefficient:

// Sequential reads (avoid unless necessary)
Read: file1
// wait for response
Read: file2
// wait for response
Read: file3

Search Strategy¶

Use Glob for patterns:

# Find all TypeScript files
Glob: pattern="src/services/web/**/*.ts"

Use Grep for content:

# Find authentication code
Grep: pattern="authentication" path="/home/chris/workspace/syrf/src"

Don't use Bash for file operations when specialized tools exist.

Common Pitfalls¶

❌ Don't: Use Relative Paths in Tool Calls¶

// Wrong
Read: docs/README.md

// Correct
Read: /home/chris/workspace/syrf/docs/README.md

❌ Don't: Assume File Structure¶

// Wrong - assuming file exists
Edit: /home/chris/workspace/syrf/src/services/auth/README.md

// Correct - verify first
Glob: pattern="src/services/**/README.md"
// Then edit confirmed path

❌ Don't: Skip YAML Frontmatter¶

// Wrong - no frontmatter
# My Feature

Description...

// Correct - include frontmatter
---
doc-type: "Feature"
status: "Draft"
author: "User"
created: 2025-11-21
updated: 2025-11-21
zenhub-ticket: "TBD"
tags: ["feature"]
---

# My Feature

Description...

Emergency Contacts¶

If uncertain about:

GitOps workflow → Read cluster-gitops/docs/
Documentation structure → Read docs/README.md
Project context → Read CLAUDE.md
Team practices → Read docs/team.md

When in doubt: Ask the user for clarification rather than making assumptions.

This guide is optimized for Claude Code and other LLM assistants working with the SyRF project.