Context Engineering

Context engineering is how we structure project knowledge so AI agents can work effectively with the Green Goods codebase. This goes beyond a single prompt -- it is the architecture of information that surrounds every agent interaction.

The .claude/ Directory

The .claude/ directory is the central guidance store for agent tooling, paired with root .plans/ as the durable repo-truth planning and execution hub:

.claude/
  context/         # Package and domain context files
  rules/           # Path-scoped coding rules
  skills/          # 10 skills -- the filesystem + SKILL.md frontmatter is the registry
  scripts/         # Hook helpers and Codex lane dispatch
  loop.md          # Maintenance loop: guidance consistency, stale references, build health
  launch.json      # Dev-server launch configs for the browser preview
  settings.json    # Global agent settings and tool execution hooks

.plans/            # Durable feature hub for briefs, specs, plan.todo, status, evals, and handoffs

Earlier iterations also kept agents/ (committed agent specs), registry/ (skill bundles), evals/, and a master skill index. The lean-skills consolidation removed them: stronger models need less scaffolding, knowledge lives in documentation referenced from CLAUDE.md/AGENTS.md, and each fact gets one home.

Context Layers

Context is loaded in layers, from broadest to most specific:

Layer 1: CLAUDE.md (Always Loaded)

The root CLAUDE.md provides universal project context: commands, architecture, key patterns, git workflow, and non-negotiable rules. Every agent session starts with this context. Keep it under 4KB.

Layer 2: AGENTS.md (Always Loaded)

A compact runtime contract for all agents -- non-negotiable invariants, code conventions, scope constraints, and pointers to canonical sources. Tools like OpenAI Codex use this as their primary context file.

Layer 3: Package Context (.claude/context/*.md)

Loaded based on which files the agent is working with:

File	Loaded When
shared.md	Editing packages/shared/
contracts.md	Editing packages/contracts/
client.md	Editing packages/client/
admin.md	Editing packages/admin/
agent.md	Editing packages/agent/
indexer.md	Editing packages/indexer/
testing.md	Writing or diagnosing tests (absorbed the old testing skill)
intent.md	Making prioritization or UX decisions
values.md	Resolving conflicts between constraints
product.md	Feature planning and requirements

Layer 4: Rules (.claude/rules/*.md)

Path-scoped rules loaded conditionally based on the files being edited:

• contracts.md -- Solidity conventions, bun script requirements
• typescript.md -- Error handling, Address type, barrel imports
• react-patterns.md -- Hook patterns, component conventions
• frontend-design.md -- UI primitives, theme tokens, accessibility
• indexer.md -- Envio handler conventions

Layer 5: Skills (Loaded on Trigger)

Skills are procedural: they encode workflows with real orchestration (review passes, the pre-merge gate, QA triage pipelines) rather than domain knowledge. A skill loads when its SKILL.md frontmatter description matches the task -- there is no separate index or registry file; the filesystem is the registry. Domain knowledge that used to live in skills (testing, react, web3, contracts, ...) moved into context/*.md and docs/, referenced from CLAUDE.md and AGENTS.md, so each fact has one home.

Session Continuity

Repository Memory Surfaces

This repository does not currently commit a repo-authoritative .claude/agent-memory/ tree. In-repo continuity currently comes from checkpoint artifacts such as session-state.md, tests.json, .plans/, and automation memory files outside the repo.

Treat any tool-local memory store as environment-specific unless it is explicitly checked into the repository. .plans/ is the durable repo truth for feature state, handoffs, and automation context; session-state.md and tests.json are disposable local checkpoints and should not outrank the active feature hub.

Do not promote .claude/agent-memory/ into committed repo truth until freshness, expiry, and ownership rules exist for that surface.

Session State

For long sessions, agents may checkpoint local progress to session-state.md:

## Session State
- **Current task**: [description]
- **Progress**: [what's done]
- **Files modified**: [list]
- **Tests**: [passing/failing/not written]
- **Next steps**: [immediate actions]

This enables context recovery after compaction or session handoff.

Guidance Governance

The standalone skill-frontmatter checker and the skills registry it validated were retired with the lean-skills consolidation -- the filesystem plus each skill's SKILL.md frontmatter is now the registry, with no version/changelog ceremony to keep in sync. Two guardrails remain:

bun run check:codex-guidance   # AGENTS.md guides and documented commands stay real

plus the .claude/loop.md maintenance loop, which runs the Codex guidance check, greps .claude/, CLAUDE.md, and AGENTS.md for references to retired surfaces (removed skills, the old registry, retired agent definitions), and spot-checks lint health. These are structural guardrails, not a semantic proof that every guidance file agrees with every other file -- routine review and human review catch semantic drift.

Design Principles

1. Layered loading -- Only load what is relevant to the current task
2. Single source of truth -- Each fact lives in one place, referenced from others
3. Machine-readable structure -- Use frontmatter, tables, and consistent headers
4. Version controlled -- All context files are committed to the repository
5. Checked drift -- check:codex-guidance and the maintenance loop catch stale references and parity drift

Next page

Next best action

Learn how to express intent clearly for AI-assisted development.

Intent Engineering

• Prompt Engineering
• Spec Engineering