Init Project

For Brownfield Projects:

• Use the Explore agent to analyze the codebase thoroughly
• Focus on: architecture patterns, tech stack, entry points, API patterns, data models, test structure, build configuration
• Use findings to inform targeted questions

2. Create .agent Directory Structure

Create the directory structure for storing project context:

mkdir -p .agent/context
mkdir -p .agent/sessions
mkdir -p .agent/archive

Create a .gitignore entry for session files (but keep context files versioned):

.agent/sessions/
.agent/archive/

3. Gather Project Information

Ask targeted questions to gather information not discoverable from the codebase. Use the AskUserQuestion tool to ask about:

Architecture & Design:

• What is the overall system architecture? (e.g., monolith, microservices, layered, event-driven)
• What are the key architectural patterns used? (e.g., MVC, MVVM, hexagonal, CQRS)
• What are the main system boundaries/modules?
• Any critical design decisions or constraints to be aware of?

Tech Stack (if not fully discoverable):

• Primary language(s) and versions
• Frameworks and major libraries
• Database(s) and data storage
• Build tools and deployment process
• Development environment requirements

Conventions:

• Naming conventions (files, variables, functions, classes)
• Code organization patterns
• Error handling approach
• Logging and monitoring practices
• Comment and documentation standards

Testing:

• Testing philosophy (unit, integration, e2e coverage expectations)
• Testing frameworks and tools
• Test organization and naming
• Mocking/stubbing approach
• CI/CD testing requirements

Key Context:

• What are the most important files/directories to understand?
• Common pitfalls or gotchas in this codebase
• Performance considerations
• Security requirements
• Dependencies to avoid or prefer

4. Generate Context Files

Based on exploration (brownfield) and user answers, create comprehensive context files:

.agent/context/architecture.md:

# System Architecture

## Overview
[High-level description of the system architecture]

## Architectural Patterns
[Key patterns: MVC, layered, event-driven, etc.]

## System Boundaries
[Main modules/services and their responsibilities]

## Design Decisions
[Critical architectural decisions and rationale]

## Constraints
[Important constraints or limitations to be aware of]

## Data Flow
[How data moves through the system]

.agent/context/tech-stack.md:

# Technology Stack

## Languages
- [Language]: [Version] - [Purpose/Usage]

## Frameworks
- [Framework]: [Version] - [Purpose/Usage]

## Libraries
### Core Dependencies
- [Library]: [Version] - [Purpose]

### Development Dependencies
- [Tool]: [Version] - [Purpose]

## Databases & Storage
- [Database]: [Version] - [Usage]

## Build & Deploy
- Build Tool: [Tool and version]
- Package Manager: [Manager and version]
- Deployment: [Process/platform]

## Development Environment
- Required tools: [List]
- Setup steps: [Key steps]

.agent/context/conventions.md:

# Coding Conventions

## File Organization
[How files and directories are organized]

## Naming Conventions
### Files
[File naming patterns]

### Variables/Functions
[Naming patterns and styles]

### Classes/Types
[Class and type naming]

## Code Patterns
### Error Handling
[How errors should be handled]

### Logging
[Logging approach and standards]

### Comments & Documentation
[When and how to comment/document]

## Code Style
[Formatting, style guide references]

## Common Patterns
[Frequently used patterns in the codebase]

## Anti-Patterns
[Things to avoid]

.agent/context/testing.md:

# Testing Approach

## Testing Philosophy
[Coverage expectations, testing pyramid]

## Test Frameworks
- Unit Tests: [Framework]
- Integration Tests: [Framework]
- E2E Tests: [Framework]

## Test Organization
[Directory structure and file naming]

## Test Patterns
### Unit Tests
[Patterns and conventions]

### Integration Tests
[Patterns and conventions]

### Mocking/Stubbing
[Approach to test doubles]

## Running Tests
```bash
# Unit tests
[command]

# Integration tests
[command]

# E2E tests
[command]

CI/CD

[Testing in CI/CD pipeline]

**`.agent/context/key-files.md`:**
```markdown
# Key Files & Directories

## Entry Points
- [File path]: [Description and purpose]

## Core Business Logic
- [Directory/File]: [What it contains]

## Configuration
- [Config file]: [What it configures]

## Infrastructure
- [File]: [Purpose]

## Common Pitfalls
[Known gotchas or common mistakes]

## Performance Considerations
[Performance-sensitive areas]

## Security
[Security-critical components or requirements]

5. Validate Context Files

Review generated files to ensure:

• All sections are filled out (no empty placeholders)
• Information is accurate based on exploration and user input
• Content is concise but comprehensive
• Files are properly formatted markdown

6. Commit Context Files

Create a git commit with the new context files:

git add .agent/context/ .gitignore
git commit -m "Initialize project context for Claude Code sessions

Add comprehensive project documentation including:
- System architecture and design patterns
- Technology stack and dependencies
- Coding conventions and standards
- Testing approach and frameworks
- Key files and common patterns"

Completion Summary

Provide a summary of what was created:

✅ Project initialization complete!

Created context files in .agent/context/:
- architecture.md - System architecture and design patterns
- tech-stack.md - Technologies, frameworks, and tools
- conventions.md - Coding standards and patterns
- testing.md - Testing approach and frameworks
- key-files.md - Key files and important information

These files will help Claude work optimally in future sessions.

Next steps:
- Use /start-session to begin work on a feature, bug, or chore
- Update context files as the project evolves

Important Notes

• Be thorough but concise: Capture essential information without overwhelming detail
• Focus on what helps Claude: Include information that will help in planning and execution
• Keep files updated: These files should evolve as the project changes
• Don't make assumptions: If exploration doesn't reveal something, ask the user
• Validate everything: Ensure generated content is accurate and complete