skill-project-overview

# Project Overview Skill (Direct Execution) Direct execution skill for analyzing a repository and creating a task with research artifact to generate `project-overview.md`. Uses a 3-stage workflow: auto-scan, interactive interview, and task+artifact creation. **Key behavior**: The skill does NOT write `project-overview.md` directly. It creates a task and research artifact, then guides the user to `/plan` and `/implement` for the actual file generation. ## Context References Reference (do not load eagerly): - Path: `@specs/TODO.md` - Current task list - Path: `@specs/state.json` - Machine state - Path: `@.opencode/context/repo/update-project.md` - Generation guide (template reference) - Path: `@.opencode/context/repo/project-overview.md` - Current project overview --- ## Execution ### Step 1: Generate Session ID ```bash session_id="sess_$(date +%s)_$(od -An -N3 -tx1 /dev/urandom | tr -d ' ')" ``` ### Step 2: Check Current State Read `.opencode/context/repo/project-overview.md` and check if it begins with `<!-- GENERIC TEMPLATE`: ```bash head -1 .opencode/context/repo/project-overview.md 2>/dev/null ``` If file does not exist or contains the generic template marker, proceed with full generation workflow. If file exists and is already customized (no generic template marker), notify the user: Use AskUserQuestion: ```json { "question": "project-overview.md already exists and appears customized. What would you like to do?", "header": "Existing Overview", "multiSelect": false, "options": [ {"label": "Regenerate from scratch", "description": "Re-scan repository and create new task to replace existing overview"}, {"label": "Cancel", "description": "Keep existing project-overview.md as-is"} ] } ``` If "Cancel" selected, display message and exit: ``` Project overview generation cancelled. Current file preserved at .opencode/context/repo/project-overview.md ``` ### Step 3: Stage 1 - Auto-Scan Repository Perform automated repository analysis using bash commands. Collect findings into structured data. #### 3.1: Directory Structure ```bash # Top-level directory listing ls -1d */ 2>/dev/null | head -20 # Key directories (check existence) for dir in src lib pkg lua tests test after doc docs; do [ -d "$dir" ] && echo "Found: $dir/" done ``` #### 3.2: Language Detection Count files by extension to identify primary languages: ```bash # Count files by extension (top 10) find . -type f -name '*.*' \ -not -path './.git/*' \ -not -path './node_modules/*' \ -not -path './.opencode/*' \ -not -path './specs/*' \ | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -10 ``` #### 3.3: Package Managers and Build Tools Check for common project configuration files: ```bash # Package managers for f in package.json Cargo.toml go.mod flake.nix pyproject.toml Gemfile composer.json; do [ -f "$f" ] && echo "Package: $f" done # Build tools for f in Makefile justfile Taskfile.yml CMakeLists.txt build.gradle build.sbt; do [ -f "$f" ] && echo "Build: $f" done ``` #### 3.4: Framework Detection Identify frameworks from config files and dependencies: ```bash # Framework-specific config files for f in next.config.js next.config.ts vite.config.ts vite.config.js \ nuxt.config.ts angular.json tsconfig.json webpack.config.js \ init.lua lazy-lock.json; do [ -f "$f" ] && echo "Framework: $f" done # Check package.json dependencies if exists if [ -f "package.json" ]; then jq -r '.dependencies // {} | keys[]' package.json 2>/dev/null | head -10 fi ``` #### 3.5: Testing Detection ```bash # Test config files for f in jest.config.js jest.config.ts vitest.config.ts pytest.ini \ .pytest.ini conftest.py setup.cfg phpunit.xml; do [ -f "$f" ] && echo "TestConfig: $f" done # Test file patterns find . -type f \( -name '*_test.*' -o -name '*_spec.*' -o -name 'test_*' \) \ -not -path './.git/*' -not -path './node_modules/*' | head -5 ``` #### 3.6: CI/CD Detection ```bash # CI/CD config files for f in .github/workflows .gitlab-ci.yml .travis.yml Jenkinsfile \ .circleci/config.yml; do [ -e "$f" ] && echo "CI: $f" done ``` #### 3.7: Key Files ```bash # Important root files for f in README.md AGENTS.md LICENSE CHANGELOG.md ROADMAP.md \ .gitignore .editorconfig .prettierrc .eslintrc*; do [ -f "$f" ] && echo "Key: $f" done ``` #### 3.8: Entry Points ```bash # Common entry points for f in main.go main.py main.rs index.ts index.js init.lua \ app.py app.ts server.ts server.js; do [ -f "$f" ] && echo "Entry: $f" done # Check src/ for entry points for f in src/main.* src/index.* src/app.*; do [ -f "$f" ] && echo "Entry: $f" done 2>/dev/null ``` Compile all findings into a structured summary for display. ### Step 4: Stage 2 - Interactive Interview Present auto-detected findings and ask verification questions. #### 4.1: Present Findings for Confirmation Display the scan results in a readable format: ``` ## Repository Scan Results **Languages detected**: {languages with file counts} **Build tools**: {list} **Package managers**: {list} **Frameworks**: {list or "None detected"} **Testing**: {test framework/config or "None detected"} **CI/CD**: {CI system or "None detected"} **Key directories**: {list} **Entry points**: {list} ``` Then ask for confirmation: Use AskUserQuestion: ```json { "question": "Are these findings accurate? Select any that need correction:", "header": "Verify Findings", "multiSelect": true, "options": [ {"label": "Languages are correct", "description": "{detected languages}"}, {"label": "Build/framework is correct", "description": "{detected build tools and frameworks}"}, {"label": "Testing setup is correct", "description": "{detected test framework}"}, {"label": "Everything looks correct", "description": "No corrections needed"}, {"label": "I need to provide corrections", "description": "Will provide corrections in next step"} ] } ``` If "I need to provide corrections" is selected, use AskUserQuestion with free text: ```json { "question": "What corrections should be made to the scan results?", "header": "Corrections" } ``` Apply corrections to the findings data. #### 4.2: Ask About Project Purpose Use AskUserQuestion: ```json { "question": "What is the primary purpose of this project?", "header": "Project Purpose" } ``` This is a free-text question. The user provides a description of what the project does. #### 4.3: Ask About Development Workflow Use AskUserQuestion: ```json { "question": "What is your typical development workflow? Select all that apply:", "header": "Dev Workflow", "multiSelect": true, "options": [ {"label": "Edit and test locally", "description": "Direct local development"}, {"label": "Build then test", "description": "Compile/build step before testing"}, {"label": "TDD/test-first", "description": "Write tests before implementation"}, {"label": "CI/CD pipeline", "description": "Automated testing and deployment"}, {"label": "REPL-driven", "description": "Interactive development environment"}, {"label": "Other", "description": "Will describe in next step"} ] } ``` If "Other" selected, ask for free text description. #### 4.4: Ask About Additional Components (Optional) Use AskUserQuestion: ```json { "question": "Are there additional components or important details I should include?", "header": "Additional Info", "multiSelect": false, "options": [ {"label": "Yes, I have more to add", "description": "Will provide additional information"}, {"label": "No, that covers it", "description": "Proceed with task creation"} ] } ``` If "Yes" selected, ask for free text. ### Step 5: Stage 3 - Create Task and Research Artifact #### 5.1: Read Current State ```bash next_num=$(jq -r '.next_project_number' specs/state.json) ``` #### 5.2: Create Task Directory and Research Artifact Compute task directory: ```bash padded_num=$(printf "%03d" "$next_num") task_slug="generate_project_overview" task_dir="specs/${padded_num}_${task_slug}" mkdir -p "${task_dir}/reports" "${task_dir}/plans" "${task_dir}/summaries" ``` Write research artifact at `${task_dir}/reports/01_project-overview-scan.md`: ```markdown # Research Report: Task #{N} **Task**: {N} - Generate project-overview.md **Started**: {ISO_DATE} **Completed**: {ISO_DATE} **Effort**: Low **Dependencies**: None **Sources/Inputs**: - Repository auto-scan - User interview responses **Artifacts**: - specs/{NNN}_{SLUG}/reports/01_project-overview-scan.md **Standards**: report-format.md, subagent-return.md ## Executive Summary - Automated scan identified {language_count} languages, {framework} framework, {build_tool} build system - User confirmed/corrected findings via interactive interview - Project purpose: {user_provided_purpose} - Development workflow: {workflow_description} ## Findings ### Technology Stack **Primary Language**: {language} **Framework/Platform**: {framework or "None"} **Build System**: {build_tool} **Package Manager**: {package_manager} **Testing Framework**: {test_framework or "None detected"} **CI/CD**: {ci_system or "None detected"} ### Directory Structure {tree output with descriptions} ### Entry Points {list of detected entry points} ### Key Files {list of important files} ### Project Purpose {user-provided purpose description} ### Development Workflow {user-selected workflow with any additional details} ### Additional Notes {any additional information from user, or "None"} ## Recommendations This report provides all information needed to generate `.opencode/context/repo/project-overview.md` using the template in `.opencode/context/repo/update-project.md`. Run `/plan {N}` to create an implementation plan, then `/implement {N}` to generate the file. ``` #### 5.3: Update state.json Add new task to active_projects: ```bash mkdir -p specs/tmp jq --argjson num "$next_num" \ --arg name "$task_slug" \ '.active_projects += [{ "project_number": $num, "project_name": $name, "status": "researched", "task_type": "meta", "next_artifact_number": 2 }] | .next_project_number = ($num + 1)' \ specs/state.json > specs/tmp/state.json && mv specs/tmp/state.json specs/state.json ``` #### 5.4: Update TODO.md Prepend new task entry to the Tasks section in TODO.md: ```markdown