---
stage: dependencies
requires: components
outputs: "{wiki_dir}/dependencies.md"
version: 2.1.0
estimated_tokens: 2000

guardrails:
  enforcement: active
  allowed_tools:
    - civyk-repoix
    - Read
    - Grep
    - Glob
    - Bash
  forbidden_actions:
    - "Delete any files"
    - "Modify any source files"
  read_only: true
---
# Stage 11: Dependency Documentation

Generate documentation of external dependencies, internal component relationships, and circular dependency analysis.

## Prerequisites

- Stage 10 completed (or skipped if no config)
- Mode: `{REPOIX_MODE}` (if "cli", convert MCP calls per AGENTS.md)
- Discovery cache loaded: LIMITS

## Critical Rules

| Rule | Action |
|------|--------|
| Config required | **MUST** verify {wiki_dir}/configuration/README.md exists (or stage skipped) |
| Analyze manifests | **MUST** analyze package manifests for external deps |
| Version context | **NEVER** document versions without noting pinned vs floating |
| Circular deps | **SHOULD** identify circular dependencies if found |

---

{{include:ai-cache-enforcement.md}}

{{include:understand-fast-path.md}}

---

## Step 1: Verify Previous Stage

```bash
civyk-hatch deepwiki-update-state verify-stage --stage=11-dependencies --wiki-dir={wiki_dir}
```

---

## Step 2: Load Discovery Cache

```bash
civyk-hatch deepwiki-update-state show --wiki-dir={wiki_dir}
# Extract: LIMITS = discovery_cache.project_size.limits
# Extract: PRIMARY_LANGUAGE = discovery_cache.file_patterns.languages.primary
```

**MCP/CLI conversion (if REPOIX_MODE == "cli"):**

| MCP Call | CLI Equivalent |
|----------|----------------|
| `architecture(action="dependencies")` | `civyk-repoix query architecture --action dependencies` |
| `quality(action="circular_deps", level="component")` | `civyk-repoix query quality --action circular_deps --level component` |
| `file(action="imports", path="...", resolve_internal=true)` | `civyk-repoix query file --action imports --path "..." --resolve-internal true` |

---

## Step 3: Get Cross-Component Dependencies

```text
# Component-level dependencies
architecture(action="dependencies")
architecture(action="components")
context(action="task", task="understand all dependencies", token_budget=2000)

# Find circular dependencies
quality(action="circular_deps", level="component")
quality(action="circular_deps", level="file")

# Code quality analysis
quality(action="dead_code", limit=100)
quality(action="duplicates", source_only=true, similarity_threshold=0.7, limit=50)
```

---

## Step 4: Get File-Level Imports

```text
# For each main file
file(action="imports", path="<main_file>", resolve_internal=true)

# Find entry points
files(pattern="**/index.*", include_stats=true, limit=50)
files(pattern="**/main.*", include_stats=true, limit=50)
files(pattern="**/__init__.py", include_stats=true, limit=50)

# Understand coupling
symbol(action="references", fqn="<key_class>")
```

---

## Step 5: Analyze Package Files

```text
# Find all package manifests
files(pattern="**/package.json", limit=20)
files(pattern="**/requirements*.txt", limit=20)
files(pattern="**/pyproject.toml", limit=10)
files(pattern="**/Cargo.toml", limit=10)
files(pattern="**/go.mod", limit=10)
files(pattern="**/pom.xml", limit=10)
files(pattern="**/build.gradle*", limit=10)

# Read each manifest
# Read file: <manifest>
# -> Extract production dependencies
# -> Extract dev dependencies
# -> Note version constraints
```

---

## Step 6: Generate Documentation

Write `{wiki_dir}/dependencies.md` using this template:

{{include:wiki/dependencies-template.md}}

**Fill placeholders with:** Dependencies summary, package manager, Mermaid dependency graph, internal/production/development dependencies tables, circular dependencies (if found).

---

## Step 7: Complete Stage

```bash
civyk-hatch deepwiki-update-state stage --stage=11-dependencies --status=completed --artifacts="{wiki_dir}/dependencies.md" --wiki-dir={wiki_dir}
```

---

## Output Format

```text
===========================================================
  STAGE COMPLETE: 11-dependencies

  Generated: {wiki_dir}/dependencies.md
  External dependencies: {count}
  Internal dependencies: {count}

  Next: Run {next_command}
===========================================================
```

---

## Edge Cases

| Scenario | Action |
|----------|--------|
| No package manager | Document from import statements |
| Vendored dependencies | Document separately |
| Monorepo internal packages | Distinguish from external |
| Native dependencies | Include system requirements |

---

## Next Stage

Run `{next_command}` - CLI auto-detects current stage and emits next prompt.
