feat: Add agents for constitution generation, instruction analysis, and feature specification

- Created `excavate.constitution.agent.md` to generate/update project constitution based on code analysis.
- Added `excavate.instructions.agent.md` for generating/updating Copilot instructions.
- Introduced `excavate.specifier.agent.md` to analyze feature documentation and generate specifications.
- Established a new constitution file at `.github/constitution.md` with core principles and governance.
- Implemented templates for feature and specification documentation in `.github/templates/`.
- Added prompt files for each agent to facilitate invocation.

Author: kbeaugrand

.github/agents/excavate.analyze.agent.md

@@ -0,0 +1,361 @@
+---
+description: Analyzes the existing application to identify and describe features, producing a comprehensive feature inventory report.
+handoffs: 
+  - label: Create specs
+    agent: excavate.specifier
+    prompt: Generate detailed feature specifications based on the analysis
+    send: true
+---
+
+## User Input
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Mission
+
+Perform a deep analysis of the existing application to extract detailed feature information. For each discovered feature, generate a comprehensive **Feature Report** including code locations, line ranges, snippets, implementation details, and concise feature descriptions.
+
+## Output Format
+
+For each feature discovered, produce a report following this structure:
+
+1. **Feature Description**: What it does, business value, and key behaviors (no user story/acceptance criteria)
+2. **Code Clues & Implementation**: Exact file paths, line ranges, and code snippets for all relevant layers discovered during analysis
+
+---
+
+## Phase 1: Discover Architecture & Structure
+
+1. **Identify Project Structure**: Analyze the workspace folders and their purposes:
+   - Use `list_dir` and `file_search` to map the complete project structure
+   - Identify all modules/components and their purposes
+   - Detect technology stacks per module by looking for dependency/build files (e.g., `package.json`, `*.csproj`, `pom.xml`, `requirements.txt`, `Cargo.toml`, `go.mod`, `build.gradle`, etc.)
+   - **Do not assume any specific technology** - discover it from the codebase
+
+2. **Read Key Configuration Files**:
+   - `.github/copilot-instructions.md` or similar project guidelines
+   - `README.md` files in each module
+   - Main configuration files relevant to the detected stack
+   - Any architecture documentation present in the repository
+
+---
+
+## Phase 2: Identify & List All Features
+
+Scan the codebase to create a **comprehensive feature list**:
+
+1. **Backend Features**:
+   - Use `list_dir` to scan API/controller/route/handler folders
+   - Use `grep_search` to find all API endpoints based on the detected framework
+   - List all endpoint handlers and business logic classes/modules
+   - Create an inventory: `[Feature Name, Entry Point File]`
+
+2. **Frontend Features** (if applicable):
+   - Scan UI components/views/pages directories
+   - Review route definitions based on the detected framework
+   - Identify main user-facing features from component/view names
+   - Create an inventory: `[Feature Name, UI File, Related Backend API]`
+
+3. **Cross-Cutting Features**:
+   - Authentication/Authorization implementations
+   - Real-time communication features (if any)
+   - External service integrations
+   - File handling features
+   - Reporting/export features
+   - Background jobs/scheduled tasks
+   - Any other infrastructure-level features
+
+**Deliverable**: A numbered list of all features found (e.g., "Found 25 features: 1. User Management, 2. File Upload, 3. ...")
+
+### Create Feature Analysis Task List
+
+After discovering all features, **create a todo task list** with one task per feature:
+
+1. **Use `manage_todo_list` tool** to create tasks for all discovered features
+2. **Each task must include**:
+   - **Title**: "Analyze [Feature Name]"
+   - **Description**: Detailed action items:
+     - Read implementation files (controllers, business logic, repositories)
+     - Extract backend code clues (endpoints, business methods, data access)
+     - Extract frontend code clues (components, state management, API calls)
+     - Capture authorization & security details
+     - Find configuration settings
+     - Identify test files
+     - Generate complete feature report following template
+   - **Status**: `not-started`
+   - **ID**: Sequential number (1, 2, 3...)
+
+3. **Task Description Format**:
+```markdown
+Analyze [Feature Name] feature and generate complete feature report:
+- [ ] Read entry point/endpoint files
+- [ ] Extract endpoint details (path, method, line range, code snippet)
+- [ ] Read business logic implementation
+- [ ] Extract business method details (line range, code snippet)
+- [ ] Read data access layer code (if applicable)
+- [ ] Extract data access details (line range, code snippet)
+- [ ] Identify entities/models used
+- [ ] Read UI components (if applicable)
+- [ ] Extract UI component details (line range, code snippet)
+- [ ] Find state management code (if applicable)
+- [ ] Find API call implementations (if applicable)
+- [ ] Extract authorization/security details
+- [ ] Search for configuration settings
+- [ ] Find related test files
+- [ ] Generate complete feature report following template
+```
+
+4. **Example Task Creation**:
+```json
+{
+  "id": 1,
+  "title": "Analyze [Feature Name]",
+  "description": "Analyze [Feature Name] feature...\n- [ ] Read entry point files\n- [ ] Extract API endpoints...",
+  "status": "not-started"
+}
+```
+
+---
+
+## Task Workflow - Managing Progress with Todo List
+
+**CRITICAL**: Use the `manage_todo_list` tool to track progress throughout the entire analysis process.
+
+### Workflow Steps
+
+1. **After Phase 2**: Create the initial todo list with all discovered features (status: `not-started`)
+
+2. **Before analyzing each feature**:
+   - Use `manage_todo_list` with `operation: "write"` to mark the current feature task as `in-progress`
+   - Only ONE task should be `in-progress` at a time
+
+3. **After generating each feature's `analyze.md`**:
+   - Use `manage_todo_list` with `operation: "write"` to mark the completed feature task as `completed`
+   - Include ALL tasks in the update (completed ones + remaining ones)
+
+4. **Progress Check**: Periodically use `manage_todo_list` with `operation: "read"` to review overall progress
+
+### Example Workflow
+
+```
+Step 1: Create initial todo list after feature discovery
+───────────────────────────────────────────────────────
+manage_todo_list(operation: "write", todoList: [
+  {id: 1, title: "Analyze User Management", status: "not-started", ...},
+  {id: 2, title: "Analyze Authentication", status: "not-started", ...},
+  {id: 3, title: "Analyze Room Management", status: "not-started", ...}
+])
+
+Step 2: Start working on first feature
+──────────────────────────────────────
+manage_todo_list(operation: "write", todoList: [
+  {id: 1, title: "Analyze User Management", status: "in-progress", ...},  // ← Now working
+  {id: 2, title: "Analyze Authentication", status: "not-started", ...},
+  {id: 3, title: "Analyze Room Management", status: "not-started", ...}
+])
+
+Step 3: After creating specs/001-user-management/analyze.md
+────────────────────────────────────────────────────────────────
+manage_todo_list(operation: "write", todoList: [
+  {id: 1, title: "Analyze User Management", status: "completed", ...},    // ← Done!
+  {id: 2, title: "Analyze Authentication", status: "in-progress", ...},   // ← Now working
+  {id: 3, title: "Analyze Room Management", status: "not-started", ...}
+])
+
+Repeat until all features are completed...
+```
+
+---
+
+## Phase 3: Generate Analysis Output Files
+
+After discovering and analyzing all features, generate the following output structure:
+
+1. **Main overview file**: `docs/analyze.md` - contains architecture overview and 1 task per feature
+2. **Feature directories**: `specs/[NNN-feature-name]/analyze.md` - contains detailed analysis per feature (e.g., `001-user-management`, `002-file-upload`)
+
+### Step 1: Create Main Overview File
+
+Use the `create_file` tool to write `docs/analyze.md` with the following structure:
+
+```markdown
+# 📊 Feature Analysis Report
+
+**Date**: [Today's date]  
+**Total Features Identified**: [Count]  
+
+---
+
+## Architecture Overview
+
+- **Technology Stack**: [Detected technologies and frameworks]
+- **Architecture Pattern**: [Discovered pattern based on code analysis]
+- **Authorization Mechanism**: [Discovered mechanism if any]
+- **Real-time Features**: [Discovered real-time capabilities if any]
+- **External Integrations**: [List of external services if any]
+
+---
+
+## Features to Analyze
+
+| # | Feature | Category | Details |
+|---|---------|----------|---------||
+| 001 | [Feature Name] | [Category] | [specs/001-feature-name/analyze.md](specs/001-feature-name/analyze.md) |
+| 002 | ... | ... | ... |
+
+---
+
+## Analysis Tasks
+
+- [ ] [001 - Feature Name](specs/001-feature-name/analyze.md)
+- [ ] [002 - Feature Name](specs/002-feature-name/analyze.md)
+- [ ] [003 - Feature Name](specs/003-feature-name/analyze.md)
+...
+
+---
+
+## Summary by Category
+
+| Category | Feature Count | Primary Files |
+|----------|---------------|---------------|
+| [Category 1] | X | [Primary files discovered] |
+| [Category 2] | X | [Primary files discovered] |
+| ... | ... | ... |
+```
+
+### Step 2: Create Feature Analysis Directories
+
+For **each discovered feature**, follow this process:
+
+#### A. Mark Task as In-Progress
+Before starting analysis of a feature, update the todo list:
+```
+manage_todo_list(operation: "write", todoList: [...all tasks with current one as "in-progress"...])
+```
+
+#### B. Create Feature Directory and Analysis File
+
+**Directory structure**: `specs/[NNN-feature-name-kebab-case]/analyze.md`
+
+Where `NNN` is a zero-padded 3-digit number (001, 002, 003, etc.) based on the order features were discovered.
+
+Use the `create_file` tool to write each feature's `analyze.md` with the following structure:
+
+```markdown
+# Feature: [Feature Name]
+
+**Category**: [Category Name]  
+**Status**: Not Analyzed  
+
+---
+
+## Description
+
+[Brief description of what the feature does and its business value]
+
+---
+
+## Code Locations
+
+### Entry Points / Endpoints
+- `[Path to endpoint/handler]` (Lines X-Y)
+
+### Business Logic
+- `[Path to business layer]` (Lines X-Y)
+
+### Data Access
+- `[Path to data layer]` (Lines X-Y) *(if applicable)*
+
+### UI Components
+- `[Path to UI component]` (Lines X-Y) *(if applicable)*
+
+---
+
+## Analysis Details
+
+- Review entry point/endpoint implementation
+- Review business logic
+- Review data access layer *(if applicable)*
+- Review UI components *(if applicable)*
+- Document API endpoints
+- Identify authorization requirements
+- Check test coverage
+
+---
+
+## Dependencies
+
+- [List any dependencies on other features or external services]
+
+---
+
+## Notes
+
+[Any additional observations or context discovered during analysis]
+```
+
+#### C. Mark Task as Completed
+**IMMEDIATELY** after creating the feature's `analyze.md` file, update the todo list:
+```
+manage_todo_list(operation: "write", todoList: [...all tasks with current one as "completed"...])
+```
+
+**Important**: Always include ALL tasks when updating the todo list (completed, in-progress, and not-started). The write operation replaces the entire list.
+
+### File Creation Instructions
+
+1. **Create directories**:
+   - `docs/` for the main overview
+   - `specs/` for feature directories
+   - `specs/[NNN-feature-name]/` for each feature (use 3-digit zero-padded number prefix + kebab-case, e.g., `001-user-management`, `002-file-upload`)
+
+2. **Generate `docs/analyze.md`** (main overview) with:
+   - Architecture overview
+   - Table of all features with links to their detailed analysis files
+   - One Markdown task checkbox (`- [ ]`) per feature linking to the feature's analyze.md
+   - Summary tables for quick reference
+
+3. **Generate `specs/[NNN-feature-name]/analyze.md`** (per feature) with:
+   - Detailed feature description
+   - All code locations with file paths and line ranges
+   - Analysis details as bullet points (no checkboxes)
+   - Dependencies and notes
+
+4. **Naming Convention**:
+   - Use 3-digit zero-padded number prefix + kebab-case for directory names (e.g., `001-user-management`, `002-file-upload`, `003-authentication`)
+   - Number features sequentially in the order they are discovered
+   - Always name the file `analyze.md` within each feature directory
+   - Use `-` (simple bullet, no checkbox) for detailed sub-items under the task
+   - This format allows another agent to pick up and perform deeper analysis on each feature
+
+---
+
+## Analysis Best Practices
+
+- **Be thorough**: Spend adequate time discovering all features before generating the output
+- **Make no assumptions**: Discover architecture, technology stack, and patterns from the codebase itself
+- **Use semantic search**: When looking for features, use semantic search to find related code
+- **Check all layers**: Ensure feature inventory covers all architectural layers discovered
+- **Document patterns**: Note coding patterns, naming conventions, and architectural decisions
+- **Organize by category**: Group related features together for easier navigation
+- **Map dependencies**: Understand how modules communicate (APIs, events, shared state)
+- **Adapt to the stack**: Use appropriate search patterns based on the discovered technology
+
+### Tools Used by This Agent
+
+- `semantic_search`: Find features by concept/functionality
+- `grep_search`: Find specific patterns, class names, or method signatures
+- `list_dir`: Explore folder structures
+- `file_search`: Find files by name pattern
+- `read_file`: Read file contents for detailed analysis
+- `manage_todo_list`: **CRITICAL** - Create, track, and update feature analysis tasks
+- `create_file`: Generate the analyze.md output file
+
+### Todo List Best Practices
+
+- **Create tasks early**: After Phase 2 feature discovery, immediately create the full todo list
+- **Update frequently**: Mark tasks in-progress BEFORE starting and completed IMMEDIATELY after
+- **One at a time**: Only have ONE task in `in-progress` status at any moment
+- **Complete list updates**: Always provide the COMPLETE todo list when writing (don't omit tasks)
+- **Track progress**: The todo list provides visibility into analysis progress for monitoring
+
+---