name: analyze-project-context
description: Use when starting work on any project (technical or non-technical) to understand structure, standards, and best practices before making changes

Analyze Project Context

Overview

Build comprehensive, evidence-based understanding of ANY project type (code, documentation, content, mixed) before making changes. Works for technical projects, content projects, documentation repositories, and everything in between.

Core principle: Discover what exists, infer patterns, document best practices, establish constitution.

When to Use

Use when:
- Starting work on a new project
- User asks to "analyze the project" or "understand the codebase"
- Before making significant changes
- Need to understand project structure and conventions
- Setting up AI agent workflow for a project

Works for:
- Software projects (Node.js, Python, Go, etc.)
- Documentation repositories
- Content projects (marketing, writing, guides)
- Mixed projects (docs + code)
- Design projects (templates, assets)
- Any organized file structure

Core Principles

• Evidence Over Assumption: Discover what exists, don't assume structure
• Pattern Recognition: Infer conventions from existing files
• Universal Applicability: Works for any project type
• Document Findings: Create AGENTS.md and constitution.md
• Depth Control: Use discovery budget (max 2-3 tool calls per category) to avoid analysis paralysis

Workflow

1. Project Type Detection

Action: Identify project type from file structure

Discovery:
- Check for README.md, README, or similar (project overview)
- Look for technical indicators: package.json, requirements.txt, Cargo.toml, go.mod, pom.xml, etc.
- Look for content indicators: docs/, content/, posts/, guides/, templates/
- Check for existing AI/agent files: .claude/, .specify/

Classify as:
- Technical: Has package managers, source code, build configs
- Content: Primarily markdown, templates, media files
- Documentation: Organized docs structure, no executable code
- Mixed: Contains both code and significant content/docs

2. Structural Discovery

Action: Map the project organization

Universal Checks:
- README.md or equivalent (purpose, structure, getting started)
- Directory structure (identify main folders and their purposes)
- File naming patterns (kebab-case, camelCase, snake_case)
- Organization principles (by feature, by type, by topic)

Technical Projects (if detected):
- Package manager files (package.json, requirements.txt, etc.)
- Source directories (src/, lib/, app/)
- Test directories (test/, __tests__/, spec/)
- Build configs and tooling

Content Projects (if detected):
- Content organization (docs/, content/, posts/, guides/)
- Templates and reusable components
- Media assets (images/, assets/, static/)
- Style guides or brand guidelines

3. Pattern & Convention Discovery

Action: Infer project conventions from existing files

Sample 3-5 representative files to extract:
- Naming conventions (files, directories, identifiers)
- Structural patterns (how are similar things organized?)
- Documentation patterns (inline comments, separate docs, both?)
- Metadata usage (frontmatter, headers, tags)

For Technical Projects:
- Code style (linters, formatters, config files)
- Testing patterns (framework, file locations, naming)
- Import/module patterns
- Error handling conventions

For Content Projects:
- Content structure (headings, sections, metadata)
- Cross-referencing patterns (links, includes, references)
- Asset organization and naming
- Version control patterns (drafts, published, archived)

4. Standards Documentation Discovery

Action: Find existing standards, guidelines, or best practices

Check for:
- CONTRIBUTING.md (contribution guidelines)
- STYLE.md or style guides
- ARCHITECTURE.md or technical docs
- AGENTS.md (AI agent best practices) - if exists
- constitution.md (project principles) - if exists
- Templates or examples directory

Extract existing standards from these files (don't reinvent what exists)

5. Technology Analysis (If Technical Project)

Action: Identify actual technology stack

Sources:
- Package manager files (dependencies, dev dependencies)
- Config files (tsconfig, babel, webpack, etc.)
- Import/require statements in source files
- Build scripts and deployment configs

Optional Validation:
- For major frameworks, verify version-specific patterns
- Check if code matches current best practices for that version
- Identify deprecated patterns or outdated dependencies

Skip this section for non-technical projects

6. Create AGENTS.md (Best Practices for AI Agents)

Action: Generate or update .claude/AGENTS.md with project-specific best practices

Structure:

# AI Agent Best Practices: [Project Name]

**Generated:** [Date]
**Project Type:** [Technical/Content/Documentation/Mixed]

## Project Overview
[From README - purpose, goals, audience]

## Working with This Project

### File Organization
- [Pattern 1]: [Explanation and examples]
- [Pattern 2]: [Explanation and examples]

### Naming Conventions
- Files: [Convention with examples]
- [Other identifiers]: [Convention with examples]

### Common Tasks
1. [Task]: [How to do it correctly]
2. [Task]: [How to do it correctly]

### Quality Standards
- [Standard 1]: [What to check]
- [Standard 2]: [What to check]

### What NOT to Do
- ❌ [Anti-pattern]: [Why to avoid]
- ❌ [Anti-pattern]: [Why to avoid]

### Technology-Specific Notes
[Only if technical project - framework versions, patterns, gotchas]

## Related Files
- Constitution: `.specify/memory/constitution.md` (if exists)
- [Other relevant docs]

Base content on discovered patterns - this is project-specific, not generic advice

7. Create/Update Constitution (Project Principles)

Action: Trigger speckit-constitution skill to create or update .specify/memory/constitution.md

If constitution doesn't exist:
- Invoke speckit-constitution skill
- Suggest principles based on discovered patterns
- Let user refine interactively

If constitution exists:
- Report path and note it was found
- Validate current project follows constitution
- Report any violations or gaps

Constitution should capture:
- Non-negotiable project principles (MUST)
- Strong recommendations (SHOULD)
- Forbidden patterns or approaches
- Quality gates and standards
- Technology constraints (if technical project)

8. Synthesis & Report

Action: Generate structured analysis report

Format:

# Project Analysis: [Project Name]

## Executive Summary
- **Project Type:** [Type]
- **Primary Purpose:** [From README]
- **Key Characteristics:** [3-5 bullet points]

## Structure
[Directory tree or organization description]

## Conventions & Patterns
[Key patterns discovered]

## Standards & Guidelines
- Existing: [List of found docs]
- Created: AGENTS.md with project best practices
- Constitution: [Created/Updated/Found at path]

## Recommendations
1. [Action]: [Reason]
2. [Action]: [Reason]

## Next Steps
[Suggested actions - use existing skills, workflows, or custom tasks]

Present options to user:
1. Review AGENTS.md and constitution.md
2. Start implementing features (use speckit workflow)
3. Run specific analysis (code quality, documentation coverage, etc.)

Anti-Patterns (What NOT to Do)

Universal Anti-Patterns

• NEVER assume project structure without verification
• NEVER create AGENTS.md with generic, non-specific advice
• NEVER skip constitution creation/update
• NEVER hallucinate file paths that don't exist
• NEVER overwrite existing standards without reviewing them first

Technical Project Anti-Patterns

• NEVER assume framework patterns without checking versions (e.g., Next.js App Router vs Pages)
• NEVER skip validation of major dependencies
• NEVER guess package manager (could be npm, yarn, pnpm, bun)

Content Project Anti-Patterns

• NEVER ignore existing content organization patterns
• NEVER assume markdown is the only format (could be MDX, AsciiDoc, reStructuredText)
• NEVER overlook asset organization and naming conventions

Common Mistakes

Quick Reference

Success Indicators

Analysis is complete when:
- ✅ Project type correctly identified
- ✅ Key directories and organization patterns discovered
- ✅ File naming and structure conventions documented
- ✅ AGENTS.md created with project-specific best practices
- ✅ Constitution created or verified
- ✅ Report generated with actionable next steps
- ✅ No assumptions made without evidence

Output

Created Files:

.claude/
└── AGENTS.md                  # Project-specific AI agent best practices

.specify/memory/
└── constitution.md            # Project principles (created or updated)

Analysis Report:
- Project classification
- Structure and conventions
- Standards documentation
- Recommendations and next steps

Related Skills

• speckit-constitution - Create/update project constitution (invoked automatically)
• speckit - Full spec-driven development workflow (suggested next step for features)
• brainstorming - Explore requirements before making changes