Shared Project Context
Relevant source files
The following files were used as context for generating this wiki page:
Shared Project Context in Roughly refers to a standardized set of documentation and configuration files that provide a unified "knowledge base" for both human developers and autonomous AI agents. By centralizing project stack information, conventions, and known issues, Roughly ensures that dispatched subagents remain project-aware without needing to ingest the entire codebase in every prompt.
This context is primarily managed through two canonical files: CLAUDE.md and .roughly/known-pitfalls.md. These files are automatically read by agents during the first step of their process to ensure adherence to established patterns and avoidance of repetitive errors.
Sources: README.md:121-127, agents/agent-preamble.md:19-21, CLAUDE.md:29-32
Architecture of Context Management
The Roughly system utilizes a "Subagent-per-task" model where every task gets a fresh agent with clean context. The Shared Project Context serves as the persistent memory that bridges these isolated executions.
Context Flow Diagram
The following diagram illustrates how Shared Project Context is initialized and subsequently consumed by various agents during the development pipeline.
Core Context Files
CLAUDE.md
CLAUDE.md is the canonical project context file. It stores the technical stack, build/test commands, and primary conventions. It is the first file any agent reads to understand the project environment.
| Component | Description | Source |
|---|---|---|
| Stack Summary | Languages, frameworks, and key libraries. | skills/setup/SKILL.md:104 |
| Build Command | The command used to compile or build the project. | skills/setup/SKILL.md:106 |
| Test Command | The command to run the project's test suite. | skills/setup/SKILL.md:110 |
| Conventions | Specific patterns (e.g., "All API routes must validate input"). | skills/setup/SKILL.md:112-113 |
| Domain | A one-sentence description of the project's purpose. | skills/setup/SKILL.md:115 |
Sources: CLAUDE.md:29-32, skills/setup/SKILL.md:101-116
.roughly/known-pitfalls.md
This file serves as a persistent record of technical "gotchas" and patterns to avoid. It prevents agents from repeating past mistakes by documenting context-specific risks.
- Initialization: Created during
/roughly:setupwith a basic boilerplate. - Maintenance: Updated by the
doc-writeragent during theWRAP-UPstage of thebuildorfixpipelines. - Thresholds: If the file exceeds 80 lines, the
doc-writersuggests reorganization or deduplication.
Sources: agents/doc-writer.md:14-25, skills/setup/SKILL.md:146-148, skills/shared/stage-8-wrap-up.md:32-34
Context Loading Mechanism
Roughly implements a manual synchronization pattern for context loading. Because the Claude Code plugin format lacks an automatic inclusion mechanism, every agent definition must inline the "Agent Preamble."
The Agent Preamble
All agents (with specific exceptions like doc-writer) follow a strict sequence in their process:
- Read CLAUDE.md — Understand project environment and rules.
- Read .roughly/known-pitfalls.md — Identify issues to avoid.
Before starting your task, read these files:
1. **CLAUDE.md** -- project conventions, commands, and stack
2. **.roughly/known-pitfalls.md** -- known issues to avoid repeating
Sources: agents/agent-preamble.md:18-21, CLAUDE.md:29-32
Context Verification and Maintenance
The Shared Project Context is not static; it is verified for accuracy and maintained for brevity.
Plan Review Verification
During the review-plan stage (Stage 4 of build/fix pipelines), a subagent verifies the implementation plan against the context files. If CLAUDE.md is missing, the review fails with a requirement to run /roughly:setup.
Sources: skills/review-plan/SKILL.md:18-24
Automated Maintenance (Doc Writer)
The doc-writer agent is dispatched at the end of successful implementation cycles if new pitfalls or conventions are identified. It categorizes discoveries and updates the appropriate files concisely.
Context-Related Configurations
Beyond Markdown files, Roughly utilizes specific configuration files to maintain the environment:
- .claudeignore: Prevents agents from ingesting large, irrelevant directories (e.g.,
node_modules,build/) which would otherwise pollute the context window. - .claude/settings.json: Stores Claude Code hooks, such as the
plan-mode-gate.sh, which protects the pipeline's context from being corrupted by simultaneous manual planning.
Sources: skills/setup/SKILL.md:149-166, README.md:25-35
Conclusion
Shared Project Context is the foundational layer of the Roughly plugin. By mandating that every autonomous agent begin its task by reading CLAUDE.md and known-pitfalls.md, the system ensures that AI-generated code remains consistent with project-specific standards while avoiding historically identified risks. This centralized knowledge approach enables the subagent-per-task architecture to function effectively without context overflow.