Context Forge

Running context-forge init generates a structured set of files to provide AI IDEs with deep project context. The output structure depends on your selected generators, but typically includes:

Core Context Files

• CLAUDE.md: Tech-stack-aware project rules.
• Docs/: Contains Implementation.md (staged dev plans), project_structure.md, and other documentation templates.
• PRPs/: Project Readiness Plans (e.g., <project>-prp.md, <feature>-prp.md) used for structured implementation.

Claude-Specific Surface (.claude/)

• .claude/settings.json: The canonical configuration for Claude Code, including hooks, MCP servers, and permissions.
• .claude/agents/: Markdown files defining sub-agents (e.g., code-reviewer.md, test-runner.md) with specific tools and models.
• .claude/skills/: Project-specific procedures (e.g., testing-protocol/SKILL.md).
• .claude/commands/: 21 specialized .md files for slash commands (e.g., orchestration, quality, migration).
• .claude/hooks/: Bash and Python scripts triggered by lifecycle events (e.g., pre-tool-use.sh, session-start.sh).

Internal Tracking

• .context-forge/config.json: A record of the initialization settings used to replay or audit the setup.

A PRP (Project Requirements Plan) is a structured markdown template used to provide comprehensive context to AI coding agents for implementing specific features. It follows a hierarchical structure designed to move from high-level goals to low-level implementation details and validation steps.

Core Sections

1. Identity & Intent: Defines the projectName, featureName, goal, and reasons (the 'Why') for the feature.
2. Contextual Requirements:
   • Success Criteria: A checklist of requirements that must be met.
   • Documentation & References: A list of URLs and the reasoning for why they must be included in the AI's context window.
   • Codebase Structure: Comparison between projectStructure (current) and desiredStructure (target).
   • Known Gotchas: Language-specific quirks or critical warnings.
3. Implementation Blueprint:
   • Data Models: Definitions for type safety and consistency.
   • Task Breakdown: A YAML-formatted list of tasks, including files to modify and specific steps.
   • Implementation Details: Pseudocode or detailed logic for each task.
   • Integration Points: Specific instructions for DATABASE, CONFIG, and ROUTES updates.
4. Validation Loop: A multi-level testing strategy:
   • Level 1 (Syntax & Style): Commands to run first to ensure code quality.
   • Level 2 (Unit Tests): Implementation of specific test cases in the target testLanguage.
   • Level 3 (Integration Test): Commands to start services and test endpoints.
   • Level 4 (Deployment & Creative Validation): Deployment commands and custom feature-specific validation.
5. Final Checklist & Anti-Patterns: A final verification list and a list of antiPatterns to avoid during implementation.

Follow this hierarchy for state management to ensure proper scoping and performance:

1. Component State: Use ref() and reactive() for state local to a single component.
2. Nuxt State: Use useState() for state that needs to be shared across components within a page.
3. Global State: Use Pinia stores for complex, application-wide state.
4. Server State: Use useFetch() or useLazyFetch() for all API-driven data.
5. Persistent State: Use useCookie() for user preferences or data that must survive refreshes.

// 1. Component state
const isOpen = ref(false);

// 2. Nuxt cross-component state
const user = useState<User | null>('user', () => null);

// 3. Pinia store
export const useAuthStore = defineStore('auth', () => {
  const user = ref<User | null>(null);
  const isAuthenticated = computed(() => !!user.value);
  
  return { user, isAuthenticated };
});

// 4. Server state
const { data: users, pending, refresh } = await useFetch<User[]>('/api/users');

// 5. Persistent state
const theme = useCookie<'light' | 'dark'>('theme', {
  default: () => 'light',
});

The planning.md template is used to generate a comprehensive Planning Document (often referred to as a PRP) for a project. It uses Handlebars-style placeholders to structure technical documentation including architecture diagrams, component breakdowns, technical decisions, and implementation phases.

When using this template, the following sections are generated:

• Executive Summary: High-level project overview.
• Architecture Overview: Visual representation via Mermaid diagrams.
• System Components: Detailed breakdown of each component's purpose, responsibilities, and dependencies.
• Data Flow: Visual representation of data movement via Mermaid diagrams.
• Technical Decisions: Documentation of options considered, the chosen path, and the rationale.
• Implementation Phases: A phased roadmap including duration, goals, deliverables, and dependencies.
• Risk Analysis: Assessment of risks including probability, impact, and mitigation strategies.
• Security, Performance, Monitoring, and Future Considerations: Specialized technical requirement sections.

A complete PRP generated from this template should follow this logical flow to ensure an AI agent can successfully complete a task:

1. Goal & Why: Defines the objective and the reasoning behind the change.
2. Success Criteria: A checklist of requirements that must be met.
3. Contextual Awareness:
   • Documentation: Links to specific docs and why they are needed.
   • AI Docs: Specific files in PRPs/ai_docs/ that are critical.
   • Codebase Trees: The current structure vs. the desired structure.
   • Gotchas: Known library quirks and framework version notes.
4. Implementation Blueprint:
   • Data Models: Definitions for type safety.
   • Task List: Ordered tasks with specific files, actions, and patterns to follow.
   • Pseudocode: Detailed logic for each task.
   • Integration Points: Specifics for Databases, Config, Routes, and Environment variables.
5. Validation Loops: Four levels of testing (Syntax, Unit, Integration, Deployment).
6. Final Checklist: A summary of quality gates (e.g., no hardcoded values, comprehensive error handling).

The base-enhanced template is the most comprehensive option, designed for full feature implementation. It focuses on deep context integration and strict quality control.

Key Features

• 4-Level Validation Gates: Syntax, Unit Tests, Integration, and Creative validation.
• AI Documentation Integration: Supports referencing curated ai_docs/ files.
• Common Fixes Section: Pre-populated solutions for typical errors.
• Integration Points: Explicit sections for Database, Config, Routes, and Environment.

When to Use

• Standard feature implementation.
• When maximum context is required.
• Projects requiring strict validation.
• Complex integrations.

## All Needed Context
- Version-specific gotchas
- Framework patterns
- Testing conventions

## Model path: app/models/

## Database Integration
- Migration patterns
- Query examples

## Implementation Blueprint
[Detailed pseudocode with validation points]

## Validation Gates

### Level 1: Syntax
✓ Run: npm run lint

### Level 2: Unit Tests
✓ Run: npm test

### Level 3: Integration
✓ Run: npm run test:e2e

### Level 4: Creative Validation
- Performance benchmarks
- Security scanning
- User acceptance

When Dart integration is enabled, Context Forge generates three specialized Python hooks that automate task management by monitoring file changes and Git activity.

1. DartProgressUpdater.py

Purpose: Automatically updates task progress based on code changes and git commits. Triggers: File creation (Write), file modification (Edit, MultiEdit), and Git commits (Bash tool with git commit). Outputs: .claude/dart_progress.json and .claude/task_suggestions.json.

2. AutoTaskCommenter.py

Purpose: Adds detailed comments to tasks by analyzing code changes. Analysis: Tracks function/line counts, assesses complexity, and categorizes files (e.g., auth, API, UI). Outputs: .claude/task_comments.json and .claude/milestone_comments.json.

3. TaskCodeMapper.py

Purpose: Maintains the relationship between tasks and code files. Detection: Uses explicit patterns (e.g., task-123), category inference (e.g., auth/), and project keywords. Outputs: .claude/task_mapping.json and .claude/task_assignments.json.