Context Network

Context Network Lifecycle

You help users build and maintain context networks—structured frameworks for organizing project knowledge that persist across sessions and support both human and agent work. Your role is to diagnose context network state, generate appropriate scaffolding, and coach users on content decisions.

Core Principle

Context networks make relationships explicit. Implicit knowledge doesn't survive session boundaries. Structure enables discovery. The goal is not completeness but navigability.

Quick Reference

Use this skill when:

• Starting a new project that needs persistent context
• Existing documentation feels scattered or hard to navigate
• Agent effectiveness is degrading due to missing context
• Context-retrospective identified gaps to address

Key states:

• CN0: No Network - Project has no context network
• CN1: Scattered Docs - Documentation exists but isn't organized as a network
• CN2: Siloed Structure - Structure exists but connections missing
• CN3: Navigation Broken - Connections exist but hard to traverse
• CN4: Guidance Unclear - Structure works but agent instructions fail
• CN5: Relationships Missing - Impacts/dependencies undocumented
• CN6: Maintenance Failing - Network exists but drifts from reality

---

The States

State CN0: No Network

Symptoms: No .context-network.md file. No context/ directory. Documentation scattered in README or absent entirely. Agent asks same questions each session.

Key Questions:

• What type of project is this? (software, research, creative, personal knowledge)
• Who will use this context? (solo, team, agents)
• What's the expected lifespan?

Interventions:

• Run Bootstrap Mode (see below)
• Generate discovery file and initial structure
• Coach on minimal viable content

State CN1: Scattered Docs

Symptoms: README.md has grown unwieldy. docs/ folder exists but files aren't connected. Architecture decisions buried in comments or commit messages. Agent finds partial info but misses connections.

Key Questions:

• What documentation already exists?
• Which docs are still accurate?
• What relationships exist between these documents?

Interventions:

• Scan for existing documentation
• Propose migration plan to context network structure
• Generate relationship mappings for migrated content

State CN2: Siloed Structure

Symptoms: Context network exists with clear directory structure. Files are well-organized within domains. But cross-references are sparse. Agent finds info within domains but misses cross-domain implications.

Key Questions:

• Which domains affect each other?
• What changes in A typically require changes in B?
• Are there shared concepts with different names in different domains?

Interventions:

• Generate relationship templates
• Coach on identifying cross-domain connections
• Create hub documents that bridge domains

State CN3: Navigation Broken

Symptoms: Information exists and is connected, but hard to find. status.md is stale. No clear entry points for common tasks. Agent reads many files to find what it needs.

Key Questions:

• What are the most common tasks agents perform?
• Which files get read most often? Least often?
• Are there orphan documents no one accesses?

Interventions:

• Create/update hub documents
• Establish task-based navigation guides
• Prune or consolidate orphan content

State CN4: Guidance Unclear

Symptoms: Context network is well-structured. CLAUDE.md exists but agents still make wrong decisions. Instructions exist but aren't followed. Agent behavior inconsistent with documented patterns.

Key Questions:

• Which agent behaviors are problematic?
• Are instructions ambiguous or contradictory?
• Is guidance too abstract to act on?

Interventions:

• Refine CLAUDE.md with specific, actionable instructions
• Add examples to abstract guidance
• Create decision trees for common choices

State CN5: Relationships Missing

Symptoms: Changes in one area unexpectedly break another. Dependencies discovered mid-task. Impact of decisions unclear until after implementation. Agent doesn't know what else to check.

Key Questions:

• What recent changes had unexpected ripple effects?
• Which components share data, state, or interfaces?
• What implicit contracts exist between areas?

Interventions:

• Document dependency maps
• Create impact relationship documentation
• Add "affects" and "affected-by" sections to key nodes

State CN6: Maintenance Failing

Symptoms: Context network was once useful but now drifts from reality. status.md describes old state. Decisions documented but not updated. Agent references outdated information.

Key Questions:

• When was the network last meaningfully updated?
• What triggers should cause updates?
• Who/what is responsible for maintenance?

Interventions:

• Establish maintenance cadence
• Define update triggers
• Integrate with context-retrospective skill for continuous improvement

---

Operational Modes

Bootstrap Mode (CN0/CN1 → CN2)

Use when starting fresh or organizing scattered documentation.

Process:

1. Existing Documentation Scan

Automatically scan for:

• README.md, docs/, documentation/
• Architecture decision records (ADRs, adr/, decisions/)
• Design docs, planning files
• Package files (package.json, Cargo.toml, pyproject.toml) for project metadata
• Existing .claude/ or memory bank structures

Report findings:

Found existing documentation:
- README.md (2.3kb) - Project overview, setup instructions
- docs/architecture.md (5.1kb) - System design
- docs/api.md (3.2kb) - API reference

Recommendation: Migrate architecture.md to context/architecture/,
keep README.md in place as user-facing doc.

2. Project Discovery Questions

Ask:

• Project type? Software / Research / Creative / Personal Knowledge
• Primary domains? (For software: frontend, backend, data, infra, etc.)
• Stakeholders? Solo / Team / Agents / Mixed
• Expected lifespan? Short-term / Long-term / Indefinite
• Which discovered docs to incorporate vs. leave in place?

3. Structure Generation

Generate based on project type:

For software projects:

context/
├── status.md           # Current state, active work
├── decisions.md        # Architecture decisions
├── glossary.md         # Domain vocabulary
├── architecture/       # System design docs
├── domains/            # Domain-specific context
│   ├── [domain-1]/
│   └── [domain-2]/
└── processes/          # Workflows, procedures

For research projects:

context/
├── status.md           # Current research state
├── decisions.md        # Methodology decisions
├── glossary.md         # Technical vocabulary
├── sources/            # Source tracking
├── findings/           # Research discoveries
└── questions/          # Open questions, hypotheses

For creative projects:

context/
├── status.md           # Current project state
├── decisions.md        # Creative decisions
├── glossary.md         # World/project vocabulary
├── world/              # Worldbuilding, setting
├── characters/         # Character information
└── structure/          # Plot, outline, structure

For personal knowledge:

context/
├── status.md           # Current focus areas
├── decisions.md        # System decisions
├── glossary.md         # Personal vocabulary
├── areas/              # Life areas (PARA-style)
├── projects/           # Active projects
└── resources/          # Reference material

Also generate:

• .context-network.md discovery file in project root
• CLAUDE.md with basic agent instructions (if not present)

4. Migration Execution

For docs user wants to incorporate:

• Copy/move to appropriate context network location
• Convert format if needed (e.g., flatten ADRs into decisions.md entries)
• Update internal cross-references
• Add relationship metadata

5. Content Coaching

Guide user to populate:

• status.md: Current state, recent changes, active work
• decisions.md: Key decisions made, rationale, date
• glossary.md: Project-specific terms, abbreviations
• Relationships between migrated content

---

Maintenance Mode (CN2-CN6 → improved state)

Use when network exists but needs improvement.

Process:

1. State Diagnosis

Analyze:

• Structure completeness: Required files present? Domains covered?
• Relationship density: Cross-references per document? Orphan files?
• Navigation paths: Clear entry points? Task-based routes?
• Guidance clarity: CLAUDE.md actionable? Instructions followed?
• Freshness: Last update dates? Stale content?

Produce diagnosis:

Current State: CN3 (Navigation Broken)

Findings:
- 23 context files, 8 with no incoming links (orphans)
- status.md last updated 3 weeks ago
- No task-based entry points defined
- Cross-domain relationships sparse (avg 1.2 per file)

Priority Issues:
1. [Critical] status.md is stale - blocks agent orientation
2. [High] 8 orphan files - content exists but undiscoverable
3. [Medium] Missing hub for API-related context

2. Gap Identification

Prioritize:

• Critical: Blocking agent effectiveness (can't find what it needs)
• High: Requires real-time discovery (agent has to search)
• Medium: Would improve efficiency (extra steps to navigate)
• Low: Nice-to-have (marginal improvement)

3. Intervention

Based on diagnosed state:

---

Retrospective Integration

Accept output from context-retrospective skill:

1. Import findings: Knowledge gaps, navigation issues, guidance assessments 2. Map to states: Which CN state do these findings indicate? 3. Prioritize: Use retrospective priority levels (Critical/High/Medium/Low) 4. Execute: Run appropriate maintenance mode interventions

---

Anti-Patterns

The Empty Scaffold

Pattern: Generating full directory structure but leaving files empty or with placeholder content only. Problem: Structure without content is worse than no structure—it creates false confidence that context exists. Fix: Generate only structure user commits to populating. Start with status.md and one domain. Expand as content accumulates.

The Kitchen Sink

Pattern: Initial network tries to anticipate every possible need. Complex taxonomies, deep hierarchies, elaborate metadata. Problem: Maintenance burden exceeds value. Network becomes intimidating. Users avoid updating it. Fix: Start minimal. Add structure only when pain emerges from its absence. Two levels of hierarchy maximum initially.

The Orphan Network

Pattern: Creating network during initial enthusiasm, then never updating it. status.md frozen in time. Problem: Stale context is worse than no context—agents act on outdated information. Fix: Establish minimal maintenance triggers: update status.md at session start/end. Schedule periodic retrospectives.

The Template Trap

Pattern: Using templates without adaptation. Every file has same sections regardless of relevance. Problem: Boilerplate obscures actual content. Templates become noise to skip. Fix: Templates are starting points, not requirements. Delete irrelevant sections. Add project-specific ones.

The Completeness Illusion

Pattern: Believing the network can/should capture everything. Adding more and more detail hoping to prevent all gaps. Problem: Signal-to-noise degrades. Navigation becomes impossible. Maintenance unsustainable. Fix: Focus on high-impact gaps. Document what agents actually need. Accept that some discovery will always be real-time.

---

Verification (Oracle)

What This Skill Can Verify

• Structure completeness - Required files exist, directories present
• Link validity - Cross-references point to existing targets
• Freshness indicators - Last-modified dates, update frequency
• Orphan detection - Files with no incoming references

What Requires Human Judgment

• Content quality - Is the information accurate and useful?
• Relationship accuracy - Do documented connections reflect reality?
• Appropriate scope - Is the network right-sized for the project?
• Navigation effectiveness - Do paths match actual usage patterns?

---

Design Constraints

This Skill Assumes

• Project benefits from persistent context across sessions
• User wants agent-accessible documentation
• Some structure is better than pure freeform notes

This Skill Does Not Handle

• Real-time project work - Route to: domain-specific skills
• Retrospective analysis of agent sessions - Route to: context-retrospective
• Framework development - Route to: skill-builder

Degradation Signals

• User wants "just a README" - may not need full network
• Project lifespan < 1 week - overhead may exceed benefit
• Pure spike/experiment - freeform notes may be better fit

---

Output Persistence

Output Discovery

Before generating structure: 1. Check for existing .context-network.md 2. Check for existing context/ directory 3. If starting fresh, confirm target location with user

Primary Output

This skill generates:

• .context-network.md - Discovery file
• context/ directory structure
• Template files (status.md, decisions.md, glossary.md)
• CLAUDE.md updates (if needed)

What Goes Where

---

Integration Graph

Inbound (From Other Skills)

Outbound (To Other Skills)

Complementary Skills

---

Example Interaction

User: "I'm starting a new TypeScript project and want to set up a context network."

Your approach: 1. Scan for existing documentation (package.json, README, etc.) 2. Ask: "What's the primary domain? (e.g., API, CLI, library, full-stack app)" 3. Generate software-project scaffold based on answer 4. Create .context-network.md and context/ structure 5. Coach: "Start with status.md - what's the current state of the project?"

Creative Project Scaffold

Directory structure and initial content for creative projects (fiction, games, screenwriting, worldbuilding).

Directory Structure

context/
├── status.md              # Current project state
├── decisions.md           # Creative decisions
├── glossary.md            # World vocabulary, naming conventions
├── world/                 # Setting and worldbuilding
│   ├── overview.md        # World summary
│   ├── locations/         # Places
│   ├── factions/          # Groups, organizations
│   └── rules/             # Magic systems, physics, constraints
├── characters/            # Character information
│   ├── index.md           # Character list
│   ├── main/              # Protagonist(s), major characters
│   └── supporting/        # Secondary characters
├── structure/             # Story structure
│   ├── outline.md         # Current outline
│   ├── arcs/              # Character arcs, plot arcs
│   └── timeline.md        # Chronology of events
└── reference/             # Research, inspiration
    ├── research.md        # Research notes
    └── inspiration/       # Reference material

Initial File Content

status.md

# Project Status

## Current State

Creative project initiated. Establishing core concepts.

## Active Work

- [ ] Define core premise
- [ ] Establish main characters
- [ ] Outline initial structure

## Project Phase

**Current Phase:** Development
**Target:** {{Draft / Outline / Pitch}}

## Recent Changes

| Date | Change | Impact |
|------|--------|--------|
| {{today}} | Project initiated | Core concepts in development |

## Creative Blockers

{{Story problems, character issues, plot holes}}

## Next Steps

1. {{Next creative task}}
2. {{Following task}}

---

*Last updated: {{today}}*

world/overview.md

# World Overview

## Purpose

High-level summary of the setting. Entry point for understanding the world.

## Classification

- **Domain:** Worldbuilding
- **Stability:** Semi-stable
- **Abstraction:** Conceptual
- **Confidence:** Evolving

## Logline

{{One-sentence world summary}}

## Core Concepts

### Setting
{{When and where. Era, location, scope.}}

### Tone
{{Mood, genre, atmosphere}}

### Central Conflict
{{What tension drives this world}}

### Rules
{{What's different from our world. Magic, technology, social structures.}}

## Key Locations

| Location | Significance |
|----------|--------------|
| {{place}} | {{why it matters}} |

## Key Factions

| Faction | Role |
|---------|------|
| {{group}} | {{their function in the story}} |

## Relationships

### Child Nodes
- locations/* - specific place details
- factions/* - group details
- rules/* - system details

## Navigation

**When to access:**
- Starting a new scene
- Checking consistency
- Introducing new elements

characters/index.md

# Character Index

## Purpose

Quick reference for all characters. Links to detailed profiles.

## Classification

- **Domain:** Characters
- **Stability:** Semi-stable
- **Abstraction:** Structural
- **Confidence:** Evolving

## Main Characters

| Character | Role | Arc | Profile |
|-----------|------|-----|---------|
| {{name}} | {{protagonist/antagonist/etc}} | {{arc summary}} | [link](main/{{name}}.md) |

## Supporting Characters

| Character | Function | Appears In | Profile |
|-----------|----------|------------|---------|
| {{name}} | {{story function}} | {{chapters/scenes}} | [link](supporting/{{name}}.md) |

## Character Relationships

{{Diagram or list of key relationships between characters}}

## Naming Conventions

- {{Convention for this world's names}}
- {{Phonetic patterns, cultural naming}}

## Relationships

### Related Nodes
- world/factions/* - belongs-to - characters affiliated with factions
- structure/arcs/* - drives - character arcs shape plot

structure/outline.md

# Story Outline

## Purpose

Current structural plan for the narrative. Living document—expect changes.

## Classification

- **Domain:** Structure
- **Stability:** Dynamic
- **Abstraction:** Structural
- **Confidence:** Evolving

## Story Shape

**Structure Type:** {{Three-act / Hero's Journey / Other}}
**POV:** {{First/Third/Multiple}}
**Timeline:** {{Linear / Non-linear}}

## Act/Section Breakdown

### Act 1: {{Title}}
**Purpose:** {{What this section accomplishes}}

1. {{Scene/Chapter}} - {{What happens}} - {{Purpose}}
2. {{Scene/Chapter}} - {{What happens}} - {{Purpose}}

### Act 2: {{Title}}
...

### Act 3: {{Title}}
...

## Key Turning Points

| Point | What Happens | Page/Chapter Target |
|-------|--------------|---------------------|
| Inciting Incident | {{event}} | {{location}} |
| Midpoint | {{event}} | {{location}} |
| Climax | {{event}} | {{location}} |

## Relationships

### Related Nodes
- characters/index.md - depends-on - structure serves character arcs
- world/overview.md - constrained-by - world rules limit plot options

Bootstrap Questions

When setting up a creative project, ask:

1. What format?

• Novel/short story: structure/, chapters
• Screenplay: scenes, dialogue focus
• Game: mechanics, player agency
• Series: episode structure, overarching plot

2. Worldbuilding depth?

• Light: minimal world/ structure
• Deep: extensive worldbuilding documentation

3. Character complexity?

• Few deep characters: detailed profiles
• Large cast: index-focused, lighter profiles

4. Collaboration?

• Solo: personal creative decisions
• Shared world: canon management, contributor guidelines

Integration Notes

• Keep outline in sync with actual progress
• Update character profiles as they evolve
• Capture creative decisions in decisions.md—prevents re-solving same problems

Personal Knowledge Scaffold

Directory structure and initial content for personal knowledge management (PKM, second brain, digital garden).

Directory Structure

context/
├── status.md              # Current focus, active projects
├── decisions.md           # System decisions
├── glossary.md            # Personal vocabulary, abbreviations
├── areas/                 # Life areas (ongoing responsibilities)
│   ├── index.md           # Area overview
│   └── [area]/            # e.g., health/, career/, finance/
├── projects/              # Active projects (with end dates)
│   ├── index.md           # Project list
│   └── [project]/         # Individual project context
├── resources/             # Reference material
│   ├── index.md           # Resource catalog
│   └── [topic]/           # Organized by subject
└── archive/               # Completed/inactive items
    ├── projects/          # Finished projects
    └── areas/             # Deprecated areas

PARA Integration

This scaffold follows the PARA method with context network enhancements:

Context network additions:

• status.md for current state across all areas
• decisions.md for system-level choices
• Explicit relationships between components

Initial File Content

status.md

# Current Status

## Focus Areas

{{What's getting attention right now}}

### This Week
- {{Primary focus}}
- {{Secondary focus}}

### This Month
- {{Larger goal}}

## Active Projects

| Project | Status | Next Action |
|---------|--------|-------------|
| {{project}} | {{status}} | {{next step}} |

## Areas Needing Attention

{{Areas that have been neglected or need review}}

## Recent Captures

{{Recent additions to the system—notes, resources, ideas}}

| Date | Item | Location | Processed |
|------|------|----------|-----------|
| {{date}} | {{what}} | {{where filed}} | Yes/No |

---

*Last updated: {{today}}*

areas/index.md

# Life Areas

## Purpose

Ongoing areas of responsibility. No end date—these persist.

## Classification

- **Domain:** Personal
- **Stability:** Static
- **Abstraction:** Structural
- **Confidence:** Established

## Active Areas

| Area | Description | Status | Last Review |
|------|-------------|--------|-------------|
| {{area}} | {{what it covers}} | {{healthy/needs attention}} | {{date}} |

## Area Health Indicators

How to assess if an area needs attention:
- {{Indicator 1}}
- {{Indicator 2}}

## Relationships

### Related Nodes
- projects/* - supports - projects often serve area goals
- resources/* - informs - resources support area maintenance

projects/index.md

# Projects

## Purpose

Active projects with defined outcomes and end states.

## Classification

- **Domain:** Personal
- **Stability:** Dynamic
- **Abstraction:** Structural
- **Confidence:** Evolving

## Active Projects

| Project | Area | Outcome | Status | Due |
|---------|------|---------|--------|-----|
| {{project}} | {{area}} | {{what done looks like}} | {{status}} | {{date}} |

## Project States

- **Active**: Currently being worked
- **Paused**: On hold, will resume
- **Waiting**: Blocked on external input
- **Review**: Evaluating if still relevant

## Someday/Maybe

Projects not committed to but might pursue:

| Project | Why Interesting | Trigger to Activate |
|---------|-----------------|---------------------|
| {{project}} | {{appeal}} | {{what would make you start}} |

## Relationships

### Related Nodes
- areas/* - serves - projects advance area goals
- archive/projects/* - completes-to - finished projects move here

resources/index.md

# Resources

## Purpose

Reference material organized by topic. Information you might need again.

## Classification

- **Domain:** Reference
- **Stability:** Semi-stable
- **Abstraction:** Structural
- **Confidence:** Established

## Resource Categories

| Category | Contents | Frequency |
|----------|----------|-----------|
| {{topic}} | {{what's here}} | {{how often accessed}} |

## Recently Added

| Date | Resource | Category | Notes |
|------|----------|----------|-------|
| {{date}} | {{what}} | {{where}} | {{why useful}} |

## Resource Quality

Not all resources are equal:
- **Core**: Frequently referenced, high value
- **Reference**: Occasionally useful
- **Archive candidate**: Rarely accessed, consider moving

## Relationships

### Related Nodes
- areas/* - supports - resources inform area work
- projects/* - supports - resources used in projects

Bootstrap Questions

When setting up a PKM system, ask:

1. What's the capture method?

• Quick capture location for inbox items
• Integration with existing tools (notes apps, bookmarks)

2. What are your life areas?

• Career, health, relationships, finance, hobbies, etc.
• Start with 3-5, expand as needed

3. Review cadence?

• Weekly review: status.md, active projects
• Monthly review: areas, resources
• Quarterly: archive, system evaluation

4. What's the retrieval pattern?

• Search-first: flat structure, good naming
• Browse-first: hierarchical, clear categories
• Link-first: heavy cross-referencing

Integration Notes

• status.md is your daily dashboard—keep it scannable
• Process inbox items regularly—unprocessed captures lose value
• Archive aggressively—completed projects don't need prime real estate
• Review decisions.md when system friction appears—may need adjustment

Research Project Scaffold

Directory structure and initial content for research projects (academic, market research, investigation).

Directory Structure

context/
├── status.md              # Current research state
├── decisions.md           # Methodology decisions
├── glossary.md            # Technical vocabulary
├── questions/             # Research questions
│   ├── primary.md         # Main research questions
│   └── emerging.md        # Questions discovered during research
├── sources/               # Source tracking
│   ├── index.md           # Source catalog
│   └── [source-type]/     # e.g., papers/, interviews/, data/
├── findings/              # Research discoveries
│   ├── index.md           # Findings overview
│   └── [topic]/           # Organized by research area
└── methodology/           # Research approach
    ├── approach.md        # Overall methodology
    └── protocols/         # Specific procedures

Initial File Content

status.md

# Research Status

## Current State

Research project initiated. Establishing scope and methodology.

## Active Work

- [ ] Define research questions
- [ ] Identify initial sources
- [ ] Establish methodology

## Research Phase

**Current Phase:** Scoping
**Next Phase:** Literature Review

## Recent Changes

| Date | Change | Impact |
|------|--------|--------|
| {{today}} | Project initiated | Research scope being defined |

## Open Questions

{{Questions that need answering to proceed}}

## Blockers

{{Access issues, resource gaps, etc.}}

---

*Last updated: {{today}}*

questions/primary.md

# Primary Research Questions

## Purpose

Central questions driving this research. All work should connect back to these.

## Classification

- **Domain:** Research
- **Stability:** Semi-stable
- **Abstraction:** Conceptual
- **Confidence:** Evolving

## Main Questions

### RQ1: {{Primary Question}}

**Why it matters:** {{Significance}}

**Scope:** {{Boundaries of this question}}

**Success criteria:** {{How we'll know when answered}}

### RQ2: {{Secondary Question}}

...

## Question Relationships

{{How questions relate to each other, dependencies}}

## Relationships

### Related Nodes
- findings/* - answers - research discoveries address these questions
- methodology/approach.md - depends-on - methodology designed to answer these

## Navigation

**When to access:**
- Starting new research thread
- Evaluating if work is on-track
- Prioritizing next steps

sources/index.md

# Source Index

## Purpose

Catalog of all sources consulted. Enables traceability and prevents duplicate work.

## Classification

- **Domain:** Research
- **Stability:** Dynamic
- **Abstraction:** Detailed
- **Confidence:** Established

## Source Categories

### Academic Papers
| ID | Citation | Status | Relevance | Notes |
|----|----------|--------|-----------|-------|
| P001 | {{citation}} | Read | High | {{key takeaway}} |

### Books
| ID | Citation | Status | Relevance | Notes |
|----|----------|--------|-----------|-------|

### Interviews/Primary
| ID | Source | Date | Status | Notes |
|----|--------|------|--------|-------|

### Web Sources
| ID | URL | Accessed | Relevance | Notes |
|----|-----|----------|-----------|-------|

## Status Legend
- **Identified**: Found, not yet reviewed
- **Skimmed**: Quick review, relevance assessed
- **Read**: Fully reviewed
- **Extracted**: Key info captured in findings

## Relationships

### Related Nodes
- findings/* - supports - findings cite these sources
- questions/primary.md - addresses - sources selected for relevance to questions

Bootstrap Questions

When setting up a research project, ask:

1. What type of research?

• Academic: emphasis on citations, methodology rigor
• Market: emphasis on data sources, competitive analysis
• Investigative: emphasis on source tracking, evidence chain

2. What's the output format?

• Paper/report: structured findings
• Presentation: key insights extraction
• Decision support: actionable recommendations

3. Timeline and scope?

• Affects depth vs. breadth tradeoffs
• Determines how much process documentation needed

4. Collaboration model?

• Solo: lighter coordination docs
• Team: source assignment, findings review process

Integration Notes

• Link findings to source IDs for traceability
• Update source status as you work
• Capture emerging questions—they often lead to best insights

Software Project Scaffold

Directory structure and initial content for software development projects.

Directory Structure

context/
├── status.md              # Current state, active work
├── decisions.md           # Architecture decisions
├── glossary.md            # Domain vocabulary, conventions
├── architecture/          # System design
│   ├── overview.md        # High-level architecture
│   └── [component].md     # Per-component details
├── domains/               # Domain-specific context
│   ├── [domain-1]/        # e.g., api/, frontend/, data/
│   └── [domain-2]/
└── processes/             # Development workflows
    ├── development.md     # Dev workflow, local setup
    ├── deployment.md      # Deploy process
    └── testing.md         # Test strategy

Common Domains

Adapt based on project type:

Initial File Content

status.md

# Project Status

## Current State

Project initialized. Context network established.

## Active Work

- [ ] Initial project setup
- [ ] Define core architecture

## Recent Changes

| Date | Change | Impact |
|------|--------|--------|
| {{today}} | Context network created | Persistent context now available |

## Next Steps

1. Document initial architecture decisions
2. Set up development workflow

---

*Last updated: {{today}}*

architecture/overview.md

# Architecture Overview

## Purpose

High-level view of system architecture. Entry point for understanding how components fit together.

## Classification

- **Domain:** Architecture
- **Stability:** Semi-stable
- **Abstraction:** Structural
- **Confidence:** Evolving

## System Diagram

{{Add architecture diagram or ASCII representation}}

## Components

| Component | Purpose | Technology |
|-----------|---------|------------|
| {{name}} | {{what it does}} | {{stack}} |

## Data Flow

{{How data moves through the system}}

## Relationships

### Related Nodes
- decisions.md - implements - architectural decisions documented here
- domains/* - is-parent-of - detailed component documentation

## Navigation

**When to access:**
- Starting work on new feature
- Understanding system boundaries
- Onboarding to project

**Next steps:**
- Specific component docs in `domains/`
- Implementation decisions in `decisions.md`

Bootstrap Questions

When setting up a software project, ask:

1. What's the primary technology stack?

• Affects vocabulary, conventions, domain structure

2. Is this greenfield or existing codebase?

• Existing: scan for documentation to migrate
• Greenfield: lighter initial structure

3. Team size?

• Solo: lighter process docs
• Team: more explicit conventions, workflows

4. Deployment model?

• Affects infra documentation needs
• CI/CD process documentation

Integration Notes

• Link to source code via relative paths when referencing implementations
• Keep architecture docs in sync with actual structure
• Update status.md at session boundaries

decisions.md Template

Track significant decisions and their rationale. Prevents re-litigating settled questions.

---

# Decisions

## How to Use This File

Record decisions that:
- Affect multiple parts of the project
- Were non-obvious or had alternatives
- Future-you or agents might question

Format: Decision, rationale, date. Keep it brief.

---

## Architecture Decisions

### {{Decision Title}}
**Date:** {{YYYY-MM-DD}}
**Status:** Active | Superseded by {{link}} | Revisiting

**Context:** {{Why this decision was needed. 1-2 sentences.}}

**Decision:** {{What was decided. Be specific.}}

**Rationale:** {{Why this option over alternatives. Key factors that drove the choice.}}

**Consequences:**
- {{Positive consequence}}
- {{Tradeoff accepted}}

---

### {{Another Decision}}
...

---

## Process Decisions

### {{Process Decision Title}}
**Date:** {{YYYY-MM-DD}}

**Decision:** {{What process/workflow was established}}

**Rationale:** {{Why this approach}}

---

## Revisit Queue

Decisions flagged for future reconsideration:

| Decision | Revisit When | Reason |
|----------|--------------|--------|
| {{decision}} | {{trigger/date}} | {{why reconsider}} |

---

Usage Notes

• Granularity: Not every choice needs recording. Focus on decisions you'd explain to a new team member.
• Status tracking: Mark decisions as Superseded when they're replaced—don't delete history.
• Revisit Queue: Captures "we'll do X for now but reconsider when Y"—prevents forgotten technical debt.
• Integration: Link to relevant context files when decisions affect specific domains.

.context-network.md Template

Use this template to create the discovery file at your project root.

---

# Project Context Network

## Location

The context network for this project is located at: `./context/`

## Purpose

This context network maintains persistent knowledge about {{PROJECT_NAME}}:
- Project state and active work
- Architecture and design decisions
- Domain-specific documentation
- Vocabulary and conventions

## Audience

- **Agents**: AI assistants working on this project
- **Maintainers**: Developers contributing to the codebase
- **Future self**: Context preservation across sessions

## What Belongs Here vs. Project Root

| Context Network (`context/`) | Project Root |
|------------------------------|--------------|
| Planning documents | Source code |
| Architecture decisions | Configuration files |
| Design discussions | User-facing documentation |
| Internal documentation | Build artifacts |
| Process documentation | Tests |

**Rule**: If it's about "how we'll build it" → Context Network. If it's "the thing we're building" → Project Root.

## Navigation

Start here:
- **Current state**: `context/status.md`
- **Key decisions**: `context/decisions.md`
- **Vocabulary**: `context/glossary.md`

## Agent Instructions

See `CLAUDE.md` for agent-specific guidance on using this context network.

---

Customization Notes

Replace:

• {{PROJECT_NAME}} with your project name
• Add project-specific navigation links as the network grows
• Extend "What Belongs Here" table with project-specific examples

glossary.md Template

Define project-specific vocabulary. Prevents agents from guessing at term meanings.

---

# Glossary

Project-specific terms, abbreviations, and conventions.

## Terms

### {{Term}}
{{Definition. What this means in the context of this project.}}

**Also known as:** {{aliases, abbreviations}}
**Not to be confused with:** {{similar terms that mean different things}}
**See also:** {{related terms, links to context}}

---

### {{Another Term}}
{{Definition}}

---

## Abbreviations

| Abbrev | Expansion | Notes |
|--------|-----------|-------|
| {{ABC}} | {{Full Name}} | {{When/where used}} |

---

## Conventions

### Naming Conventions

- **Files:** {{pattern, e.g., kebab-case}}
- **Functions:** {{pattern}}
- **Variables:** {{pattern}}
- **Branches:** {{pattern, e.g., feature/ABC-123-description}}

### Code Conventions

- {{Convention 1: what and why}}
- {{Convention 2}}

---

## Domain-Specific Vocabulary

### {{Domain Name}}

| Term | Meaning |
|------|---------|
| {{term}} | {{meaning in this domain}} |

---

Usage Notes

• Add terms as confusion arises: Don't pre-populate exhaustively. Add when you notice agents or humans confused.
• Context matters: Same term may mean different things in different domains—capture that.
• Link to sources: For external/standard terms, link to authoritative definitions.
• Conventions section: Especially important for agents—explicit patterns prevent guessing.

Node Template

Standard format for context network information nodes. Use for domain-specific documentation.

---

# {{Node Title}}

## Purpose

{{Why this node exists. What question does it answer? 1-2 sentences.}}

## Classification

- **Domain:** {{Primary knowledge area: Frontend, Backend, Design, etc.}}
- **Stability:** {{Static | Semi-stable | Dynamic}}
- **Abstraction:** {{Conceptual | Structural | Detailed}}
- **Confidence:** {{Established | Evolving | Speculative}}

## Content

{{Primary information. Organize appropriately for the content type.}}

### {{Subsection if needed}}

{{Details}}

## Relationships

### Parent Nodes
- {{Link to broader context}}

### Related Nodes
- {{Link}} - {{relationship type}} - {{brief description}}
- {{Link}} - depends-on - {{what dependency exists}}
- {{Link}} - impacts - {{what this affects}}

### Child Nodes
- {{Link to more specific details}}

## Navigation

**When to access this node:**
- {{Scenario 1}}
- {{Scenario 2}}

**Common next steps:**
- {{Where to go from here}}

**Related tasks:**
- {{What work involves this node}}

---

## Metadata

- **Created:** {{date}}
- **Last Updated:** {{date}}
- **Updated By:** {{agent/person}}

## Change History

- {{date}}: {{what changed}}

---

Usage Notes

Classification Values

Stability:

• Static: Fundamental principles, unlikely to change
• Semi-stable: Established patterns, evolve gradually
• Dynamic: Frequently changing information

Abstraction:

• Conceptual: High-level ideas and principles
• Structural: Organizational patterns and frameworks
• Detailed: Specific implementations and examples

Confidence:

• Established: Verified, reliable
• Evolving: Partially validated, subject to refinement
• Speculative: Exploratory, requires validation

Relationship Types

Use consistent vocabulary:

• depends-on: This node requires the target
• implements: Concrete implementation of target concept
• extends: Builds upon target
• contradicts: Presents opposing view
• complements: Works alongside target
• impacts: Changes here affect target
• interfaces-with: Connects across domain boundaries

When to Create a Node

Create a new node when:

• Information doesn't fit existing nodes
• Topic deserves dedicated navigation entry
• Multiple other nodes reference this concept

Don't create a node when:

• Information fits as a section in existing node
• Content is too thin to stand alone
• Better as entry in glossary

status.md Template

The status file is the primary entry point for agents. Keep it current.

---

# Project Status

## Current State

{{Brief description of where the project is right now. 1-3 sentences.}}

## Active Work

{{What's currently being worked on. Update at session start/end.}}

- [ ] {{Active task 1}}
- [ ] {{Active task 2}}

## Recent Changes

{{Last 3-5 significant changes. Helps agents understand recent context.}}

| Date | Change | Impact |
|------|--------|--------|
| {{date}} | {{what changed}} | {{what it affects}} |

## Blockers

{{Anything blocking progress. Remove when resolved.}}

- {{Blocker description}} - Blocked since: {{date}}

## Next Steps

{{What comes after current work. Helps agents understand trajectory.}}

1. {{Next step 1}}
2. {{Next step 2}}

---

*Last updated: {{date}} by {{who/what}}*

---

Usage Notes

• Update frequency: At minimum, start and end of each work session
• Keep it scannable: Agents read this first; density over length
• Active Work: Should reflect actual current state, not aspirational backlog
• Recent Changes: Rotate out changes older than ~2 weeks
• Blockers: Critical section—stale blockers mislead agents