Agent Context Management

Relevant source files

• .github/workflows/scripts/create-release-packages.ps1
• scripts/bash/update-agent-context.sh
• scripts/powershell/update-agent-context.ps1

Purpose and Scope

Agent Context Management maintains agent-specific context files that provide AI coding assistants with up-to-date project information. These context files are automatically updated from plan.md specifications to ensure agents understand the current technology stack, project structure, and recent changes.

This page documents the update-agent-context scripts (both Bash and PowerShell variants) that parse feature specifications and generate or update agent context files. For information about which AI agents are supported, see Supported AI Agents. For details on the AGENT_CONFIG registry and agent metadata, see Agent Configuration System. For agent-specific directory structures and command formats, see Multi-Agent Architecture.

Sources: scripts/bash/update-agent-context.sh1-40 scripts/powershell/update-agent-context.ps11-30

---

Agent Context Files Overview

Agent context files serve as persistent memory for AI coding assistants, containing project-specific information that agents reference during development workflows. Each supported agent has its own context file format and location convention.

Agent	Context File Path	Format	Purpose
Claude Code	CLAUDE.md	Markdown	Root-level context file
Gemini CLI	GEMINI.md	Markdown	Root-level context file
GitHub Copilot	.github/agents/copilot-instructions.md	Markdown	Workspace instructions
Cursor IDE	.cursor/rules/specify-rules.mdc	Markdown	IDE rules file
Qwen Code	QWEN.md	Markdown	Root-level context file
Windsurf	.windsurf/rules/specify-rules.md	Markdown	IDE rules file
Kilo Code	.kilocode/rules/specify-rules.md	Markdown	IDE rules file
Auggie CLI	.augment/rules/specify-rules.md	Markdown	Rules file
Roo Code	.roo/rules/specify-rules.md	Markdown	Rules file
CodeBuddy CLI	CODEBUDDY.md	Markdown	Root-level context file
Qoder CLI	QODER.md	Markdown	Root-level context file
Amazon Q	AGENTS.md	Markdown	Shared context file
opencode/Codex/Amp/SHAI/IBM Bob	AGENTS.md	Markdown	Shared context file

Context files contain standardized sections including:

• Active Technologies: Language, framework, database stack with feature branch references
• Project Structure: Directory organization based on project type
• Build/Test Commands: Language-specific commands for the current stack
• Coding Conventions: Language-specific style guidelines
• Recent Changes: Last 3 feature additions with timestamps
• Last Updated: ISO date timestamp

Sources: scripts/bash/update-agent-context.sh61-78 scripts/powershell/update-agent-context.ps146-62

---

Context Update Architecture

The context management system consists of parallel Bash and PowerShell implementations that share identical logic and maintain feature parity.

System Components Diagram

Sources: scripts/bash/update-agent-context.sh50-56 scripts/powershell/update-agent-context.ps134-44

---

Plan Data Extraction

The scripts extract structured metadata from plan.md files using pattern matching against standardized field names.

Extracted Fields

Field Pattern	plan.md Key	Purpose	Example Value
Language/Version	**Language/Version**: Python 3.12	Primary language and version	Python 3.12
Primary Dependencies	**Primary Dependencies**: FastAPI	Framework/libraries	FastAPI, SQLAlchemy
Storage	**Storage**: PostgreSQL	Database or storage layer	PostgreSQL 15
Project Type	**Project Type**: Web API	Application category	Web API, CLI Tool, Library

Field Extraction Implementation

The extract_plan_field() function uses grep and sed in Bash, or regex matching in PowerShell, to parse field values:

Bash Implementation:

PowerShell Implementation:

The extraction handles missing fields gracefully, returning empty strings when fields are absent or contain placeholder values.

Sources: scripts/bash/update-agent-context.sh156-166 scripts/powershell/update-agent-context.ps1123-139

---

Agent File Management

Agent files are managed through a create-or-update pattern with atomic file operations and permission validation.

File Management Workflow

Directory Structure Creation

Agent files may reside in nested directories that must be created before writing:

Agent	Directory Creation	Notes
Claude/Gemini/Root files	None required	Root-level files
GitHub Copilot	mkdir -p .github/agents	Requires .github structure
Cursor IDE	mkdir -p .cursor/rules	Requires .cursor structure
Windsurf	mkdir -p .windsurf/rules	IDE-specific directory
Kilo Code	mkdir -p .kilocode/rules	IDE-specific directory
Auggie CLI	mkdir -p .augment/rules	Rules directory
Roo Code	mkdir -p .roo/rules	Rules directory

Sources: scripts/bash/update-agent-context.sh507-575 scripts/powershell/update-agent-context.ps1340-366

---

Template-Based File Generation

New agent context files are generated from a single template with dynamic placeholder substitution.

Template File Location

The template resides at .specify/templates/agent-file-template.md and is created during specify init. It contains placeholders that are replaced with project-specific values.

Template Placeholder Mapping

Placeholder	Replacement Value	Source
[PROJECT NAME]	Repository directory name	basename $REPO_ROOT
[DATE]	Current date (ISO format)	date +%Y-%m-%d
[EXTRACTED FROM ALL PLAN.MD FILES]	Technology stack entries	Formatted from parsed fields
[ACTUAL STRUCTURE FROM PLANS]	Project directory structure	get_project_structure()
[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES]	Build/test commands	get_commands_for_language()
[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE]	Coding conventions	get_language_conventions()
[LAST 3 FEATURES AND WHAT THEY ADDED]	Recent change entry	Current branch + tech stack

Technology Stack Formatting

The technology stack is formatted conditionally based on available data:

Example outputs:

• Both: - Python 3.12 + FastAPI (001-api-endpoints)
• Language only: - Python 3.12 (001-api-endpoints)
• Framework only: - FastAPI (001-api-endpoints)

Language-Specific Command Generation

The get_commands_for_language() function generates appropriate build/test commands:

Bash Implementation:

PowerShell Implementation:

Sources: scripts/bash/update-agent-context.sh236-263 scripts/powershell/update-agent-context.ps1160-201 scripts/bash/update-agent-context.sh270-358 scripts/powershell/update-agent-context.ps1203-265

---

Update Mechanisms

Existing agent files are updated incrementally, preserving manual additions while injecting new project information.

Section-Based Update Algorithm

Active Technologies Section Update

New technology entries are appended to the "Active Technologies" section if they don't already exist:

The entries are inserted before the section closes (next ## header or empty line).

Recent Changes Section Update

The Recent Changes section maintains a rolling 3-entry history:

1. New change entry is inserted immediately after the ## Recent Changes header
2. Existing changes are read and the first 2 are kept
3. Changes beyond the first 2 are discarded

Timestamp Update

The **Last updated**: YYYY-MM-DD line is located and the date is replaced:

Sources: scripts/bash/update-agent-context.sh363-502 scripts/powershell/update-agent-context.ps1267-338

---

Multi-Agent Support

The scripts support updating a single agent or all existing agent files in one operation.

Agent-Specific Update Functions

Each agent has a dedicated update case in update_specific_agent():

Bash Implementation:

PowerShell Implementation:

Update All Existing Agents

When no agent type is specified, the script checks for existing agent files and updates all found:

This ensures that:

• Projects with multiple agents keep all agent files synchronized
• New projects get a default Claude file
• No unnecessary files are created for unused agents

Sources: scripts/bash/update-agent-context.sh581-642 scripts/bash/update-agent-context.sh644-728 scripts/powershell/update-agent-context.ps1368-393 scripts/powershell/update-agent-context.ps1395-418

---

Usage Patterns

Command-Line Invocation

Update specific agent:

Update all existing agents:

Environment Requirements

The scripts require the following environment state:

Requirement	Git Mode	Non-Git Mode	Validation Function
Current feature	Git branch name	$SPECIFY_FEATURE env var	validate_environment()
Repository root	Git root directory	$SPECIFY_REPO_ROOT env var	get_feature_paths()
plan.md exists	specs/$BRANCH/plan.md	specs/$FEATURE/plan.md	File existence check
Template exists	.specify/templates/agent-file-template.md	Same	File existence check

Git mode example:

Non-Git mode example:

Integration with Workflow Commands

The context update scripts are typically invoked by workflow commands after plan generation:

Sources: scripts/bash/update-agent-context.sh37-40 scripts/powershell/update-agent-context.ps114-30 scripts/bash/update-agent-context.sh123-150 scripts/powershell/update-agent-context.ps1104-121

---

Error Handling and Validation

Environment Validation

The validate_environment() function checks preconditions before processing:

Validation checks:

1. Current branch/feature determination: Ensures $CURRENT_BRANCH is set

   • Git mode: Uses current Git branch
   • Non-Git mode: Requires $SPECIFY_FEATURE environment variable
   • Failure: Exits with error and usage hint

2. Plan file existence: Verifies plan.md exists at expected location

   • Path: $REPO_ROOT/specs/$CURRENT_BRANCH/plan.md
   • Failure: Exits with error suggesting feature creation

3. Template availability: Checks for agent file template (warning only)

   • Path: $REPO_ROOT/.specify/templates/agent-file-template.md
   • Failure: Warning logged; new file creation will fail but updates proceed

File Operation Safety

Atomic updates: Temporary files are used for all modifications:

Permission checks:

Cleanup trap: Bash version registers cleanup handler:

Sources: scripts/bash/update-agent-context.sh104-150 scripts/powershell/update-agent-context.ps1104-121 scripts/bash/update-agent-context.sh109-118

---

Data Flow Summary

The complete data flow from specification to agent context:

This data flow ensures that:

1. All agent files receive consistent project information
2. Technology stack changes are immediately visible to agents
3. Historical context is preserved in Recent Changes
4. Manual additions to agent files are not overwritten
5. New features automatically update all active agents

Sources: scripts/bash/update-agent-context.sh168-206 scripts/bash/update-agent-context.sh208-230 scripts/bash/update-agent-context.sh507-575 scripts/powershell/update-agent-context.ps1141-158 scripts/powershell/update-agent-context.ps1203-265