Context Awareness

Enriches tasks with deep project context by leveraging dotcontext's semantic analysis (Full mode), .context/ files (Lite mode), or direct exploration (Minimal mode).

Announce at start: "I'm using the devflow:context-awareness skill to gather project context."

When to Invoke

• Before brainstorming (prevc-planning calls this automatically)
• When entering a new area of the codebase
• When making architectural decisions
• When resolving a bug in unfamiliar code
• When a task requires understanding existing patterns

Context Gathering by Mode

Full Mode — Semantic Analysis

Always run these three to get comprehensive context:

context({ action: "buildSemantic" })   # AST analysis, symbols, deps, cross-file refs
context({ action: "getMap" })          # Codebase map (file tree + descriptions + stats)
context({ action: "detectPatterns" })  # Architecture patterns and conventions

Returns:

• Complete codebase structure with file relationships
• Symbol definitions and references (via tree-sitter)
• Dependency graph
• Architecture patterns (MVC, service layer, repository, etc.)
• Code conventions and organization style

Task-specific queries:

context({ action: "searchQA" })       # Search project Q&A knowledge base
explore({ action: "analyze", path: "<file>" })  # Deep analysis of specific file
explore({ action: "search", query: "<term>" })   # Semantic code search
explore({ action: "getStructure" })   # Full directory structure

Tip: buildSemantic + getMap + detectPatterns should be run together — they complement each other. buildSemantic gives symbols, getMap gives structure, detectPatterns gives architectural context.

Lite Mode — Direct File Reading

Read these files in order (stop when you have enough context):

1. Project overview: .context/docs/project-overview.md

   • Project description, goals, architecture summary

2. Codebase map: .context/docs/codebase-map.json

   • File structure, component descriptions, dependencies

3. Development workflow: .context/docs/development-workflow.md

   • Branch strategy, CI/CD, coding conventions

4. Testing strategy: .context/docs/testing-strategy.md

   • Test framework, coverage expectations, test patterns

5. Tooling: .context/docs/tooling.md

   • Build tools, linters, formatters, deployment

6. ADR Guardrails: .context/docs/adrs/README.md

   • Active architectural decisions and guardrails
   • Read README index, then relevant ADRs by stack/category

7. Agent playbooks (for domain-specific context):

   • .context/agents/<relevant-agent>.md

8. Skill files (for task-specific guidance):

   • .context/skills/<relevant-skill>/SKILL.md

Minimal Mode — Direct Exploration

Standard code exploration:

1. Read README.md, CONTRIBUTING.md, package.json/Cargo.toml/go.mod
2. Explore directory structure
3. Read recent git log for context on current work
4. Read key files in the area being modified

Tip: If Minimal mode, suggest running /devflow init to scaffold .context/ and unlock Lite mode.

.context/ Compatibility

DevFlow reads .context/ files generated by either system:

• dotcontext (npm i -g @dotcontext/cli && dotcontext mcp:install claude --local, then use MCP tools) — produces the richest content with semantic analysis
• devflow:project-init (/devflow init) — produces good content via codebase exploration

Both use the same dotcontext v2 frontmatter format (scaffoldVersion: "2.0.0"). Files from either source are interchangeable.

Priority rule: If a file has status: filled, trust it regardless of origin. If status: unfilled, it's a scaffold waiting to be enriched — DevFlow can fill it during context gathering.

Context Output Format

After gathering context, summarize for the consuming skill:

## Project Context

**Type:** [CLI / Web / Library / API / Monorepo]
**Stack:** [key technologies]
**Patterns:** [key patterns found — e.g., "service layer + repository pattern"]

### Relevant Files
- `path/to/file.ts` — [what it does, why it's relevant]

### Conventions
- [coding conventions discovered]

### Dependencies
- [key dependencies relevant to the task]

### Active ADR Guardrails
- [list of guardrails from relevant ADRs]

### Recent Activity
- [recent changes in the area being modified]

Context Caching

Full Mode

dotcontext caches semantic context automatically. Re-building is only needed when:

• Significant code changes since last build
• Entering a different area of the codebase

Lite Mode

Context files are static — read once per session unless the task modifies them.

Minimal Mode

No caching — explore as needed.

Anti-Patterns

Thought	Reality
"I know this codebase"	Context changes. Gather fresh context, especially after other agents worked.
"Context gathering is slow"	In Full mode it's cached. In Lite mode it's a few file reads. Worth it.
"I'll just read the relevant file"	Isolation without context leads to inconsistent code. Understand the whole.
"Semantic analysis is overkill"	Only available in Full mode. In Lite/Minimal, context is lightweight.