project-exploration

name	project-exploration
model	sonnet
description	Produces an Exploration Brief rating a project GREEN/YELLOW/RED for collaboration fit, with architecture snapshot, resonance map, and ranked entry points. Use when: 'explore this project', 'assess this codebase', 'should we collaborate on this', 'onboard me to this repo', 'evaluate this project for fit'.
category	continuous-learning
triggers	["explore this project","assess this codebase","should we collaborate on this","onboard me to this repo","evaluate this project for fit"]
tier	1
agents	["primary"]
tool_dependencies	["file_system"]
inputs	[{"name":"repo_path","type":"string","description":"Path or URL to the project/repository to explore","required":true}]
outputs	[{"name":"exploration_brief","type":"string","description":"Exploration Brief rating the project GREEN/YELLOW/RED with architecture snapshot, resonance map, and ranked entry points"}]

Project Exploration Skill

Version: 1.0 Author: Tres Pies Design Purpose: Structured process for respectfully exploring a new project to determine collaboration readiness and fit before committing.

---

Philosophy: Exploration Before Commitment

When encountering a large project or codebase, explore its philosophy and patterns before diving into implementation. The goal is not just to understand the code, but to understand the project's relationship to your goals, values, and existing knowledge.

---

Core Principles

• Progressive Disclosure: Do not attempt to read everything at once. Start with a high-level overview and drill down as needed.
• Incremental Synthesis: Save findings as you go. Externalize understanding to prevent information loss.
• Seek Conceptual Clarity: Prioritize understanding the core philosophy, values, and goals before implementation details.
• Map Connections: Understand the project's relationship to your existing knowledge and skills. Explicitly map resonances.
• Express Genuine Enthusiasm: Collaboration is relational. Output should reflect genuine interest and readiness to contribute.

---

When to Use This Skill

• Invited to collaborate on a project with a large existing codebase
• Evaluating whether to adopt a library, framework, or tool
• Onboarding to a new team's repository
• Assessing whether a project's architecture supports your goals

---

The 5-Phase Exploration Process

Phase 1: First Impressions — Map the Terrain

Get a high-level overview of structure and scope.

1. Read the README — What is this project? Who built it? What's its stated purpose?
2. Scan project structure — List top-level directories and key files. Identify organizational patterns.
3. Check recent activity — Last commit, release cadence, contributor count. Is this project alive?
4. Document initial findings — Create an initial overview of themes, structure, and first impressions.

Output: Project overview with structure analysis and activity assessment.

Phase 2: Architecture Mapping — Taste the Water

Select 2-3 key documents or files to understand core content and patterns.

1. Identify entry points — Main module, config files, core abstractions
2. — Use semantic-clusters approach: what does this project actually ?