Analyze Project Context

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: .codex/, .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 .codex/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:

.codex/
└── 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