Project Orientation

Overview

This skill helps agents quickly understand where a project is, where it's going, and what needs to happen next - without reviewing the entire codebase or documentation from scratch.

When to Use

Automatically:

• After git commits (can be integrated into git hooks)
• When major milestones are completed

Manually:

• When starting a new session
• When switching between different AI agents
• When returning to a project after time away
• When onboarding new team members

The Process

Reading Project State (Orient Mode)

When invoked without arguments, read and synthesize:

1. Check for state file: Look for project/STATE.md
2. Analyze git context:
   • Current branch and recent commits (last 10)
   • Active branches and their purposes
   • Recent merge activity
3. Scan key documentation:
   • README.md for project overview
   • ROADMAP.md if it exists
   • docs/ directory for recent changes
4. Present concise summary:
   • Current focus area (what's being worked on now)
   • Recent completions (what just finished)
   • Next steps (what's coming up)
   • Active decisions or blockers
   • Key context for continuity

Updating Project State (Update Mode)

When invoked with --update or after a commit:

1. Gather context:

   • What was just completed (from commit or user input)
   • What changed (technical details)
   • Why it changed (decisions, rationale)
   • What's next (immediate next steps)
   • Any blockers or open questions

2. Update project/STATE.md:

   • Append to history
   • Update current focus
   • Refresh next steps
   • Document decisions made
   • Note any blockers

3. Keep it concise:

   • Focus on "why" not just "what"
   • Include enough context for continuity
   • Remove stale information
   • Keep file under 500 lines

File Format: project/STATE.md

The state file is structured for both human and LLM readability:

# Project State

Last Updated: YYYY-MM-DD HH:MM
Current Branch: feature/xyz

## Current Focus

[What's being worked on right now - 2-3 sentences]

## Recent Completions

- YYYY-MM-DD: [What was completed and why it matters]
- YYYY-MM-DD: [What was completed and why it matters]

## Next Steps

1. [Immediate next task with context]
2. [Following task with context]
3. [Upcoming task with context]

## Active Decisions & Context

### [Decision/Topic Name]
- **Context**: Why this matters
- **Options Considered**: Brief summary
- **Current Direction**: What was chosen and why
- **Open Questions**: What's still unclear

## Blockers

- [Blocker description and impact]

## Key Technical Context

### Architecture Notes
- [Important architectural decisions]
- [Patterns being followed]

### Dependencies & Integration
- [Key dependencies and their status]
- [Integration points to be aware of]

## History (Last 30 Days)

### YYYY-MM-DD: [Milestone/Feature Name]
- **What**: Brief description
- **Why**: Rationale
- **Impact**: What changed
- **Decisions**: Key choices made

Usage Examples

Starting a Session

User: /project-orientation
Agent: [Reads project/STATE.md and presents summary]

After a Commit (Manual)

User: /project-orientation --update
Agent: [Asks about what was completed, updates state file]

Git Hook Integration

Add to .git/hooks/post-commit:

#!/bin/bash
# Optionally trigger project state update
# <your-agent-cli> skill project-orientation --update --auto

Key Principles

• Concise but Complete: Include enough context for continuity, not exhaustive details
• Why Over What: Focus on rationale and decisions, not just changes
• Living Document: Keep it current, remove stale info
• LLM-Friendly: Structure for easy parsing and synthesis
• Human-Readable: Should be useful for humans too
• No External Dependencies: Pure file-based, works offline

Implementation Notes

When implementing this skill:

1. Create state file if missing: Initialize with current project analysis
2. Preserve history: Don't delete old entries, just move to history section
3. Smart summarization: Condense when file gets too long
4. Git-aware: Use git context to infer state when possible
5. Flexible format: Allow variations in structure as long as key sections exist