菜单
Interactive repository analysis and project-overview.md generation via task creation. Invoke for /project-overview command.
Scan codebase for FIX:/NOTE:/TODO:/QUESTION: tags and create structured tasks with interactive selection. Invoke for /fix-it command.
Research blockers and spawn new tasks to overcome them, updating parent task dependencies
Archive completed and abandoned tasks with CHANGE_LOG.md updates and memory harvest suggestions
Execute general implementation tasks following a plan. Invoke for general implementation work.
Create phased implementation plans from research findings. Invoke when a task needs an implementation plan.
Conduct general research using web search, documentation, and codebase exploration. Invoke for general research tasks.
| name | skill-project-overview |
| description | Interactive repository analysis and project-overview.md generation via task creation. Invoke for /project-overview command. |
| allowed-tools | Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion |
| context | direct |
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.
Reference (do not load eagerly):
@specs/TODO.md - Current task list@specs/state.json - Machine state@.claude/context/repo/update-project.md - Generation guide (template reference)@.claude/context/repo/project-overview.md - Current project overviewsession_id="sess_$(date +%s)_$(od -An -N3 -tx1 /dev/urandom | tr -d ' ')"
Read .claude/context/repo/project-overview.md and check if it begins with <!-- GENERIC TEMPLATE:
head -1 .claude/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:
{
"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 .claude/context/repo/project-overview.md
Perform automated repository analysis using bash commands. Collect findings into structured data.
# 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
Count files by extension to identify primary languages:
# Count files by extension (top 10)
find . -type f -name '*.*' \
-not -path './.git/*' \
-not -path './node_modules/*' \
-not -path './.claude/*' \
-not -path './specs/*' \
| sed 's/.*\.//' | sort | uniq -c | sort -rn | head -10
Check for common project configuration files:
# 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
Identify frameworks from config files and dependencies:
# 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
# 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
# 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
# Important root files
for f in README.md CLAUDE.md LICENSE CHANGELOG.md ROADMAP.md \
.gitignore .editorconfig .prettierrc .eslintrc*; do
[ -f "$f" ] && echo "Key: $f"
done
# 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.
Present auto-detected findings and ask verification questions.
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:
{
"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:
{
"question": "What corrections should be made to the scan results?",
"header": "Corrections"
}
Apply corrections to the findings data.
Use AskUserQuestion:
{
"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.
Use AskUserQuestion:
{
"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.
Use AskUserQuestion:
{
"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.
next_num=$(jq -r '.next_project_number' specs/state.json)
Compute task directory:
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:
# 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 `.claude/context/repo/project-overview.md` using the template in `.claude/context/repo/update-project.md`.
Run `/plan {N}` to create an implementation plan, then `/implement {N}` to generate the file.
Before writing the task to state.json, offer an interactive topic picker:
# Get existing active topics from state.json
mapfile -t existing_topics < <(bash .claude/scripts/manage-topics.sh list)
# Build options: existing topics + "New topic..." + "Skip (no topic)"
Show picker via AskUserQuestion:
{
"question": "Assign a topic to this task?",
"header": "Topic",
"multiSelect": false,
"options": ["<existing-topic-1>", "<existing-topic-2>", "New topic...", "Skip (no topic)"]
}
topic="$selected"{"question": "Enter new topic name (lowercase, kebab-case, e.g. 'agent-system'):"}
topic. Validate: non-empty, no spaces.topic=""Add new task to active_projects:
jq --argjson num "$next_num" \
--arg name "$task_slug" \
--arg topic "$topic" \
'.active_projects += [{
"project_number": $num,
"project_name": $name,
"status": "researched",
"task_type": "meta",
"topic": (if ($topic == "" | not) then $topic else null end),
"next_artifact_number": 2
} | if .topic == null then del(.topic) else . end] | .next_project_number = ($num + 1)' \
specs/state.json > specs/state.json.tmp && mv specs/state.json.tmp specs/state.json
After the state.json write, assign topic via manage-topics.sh (non-blocking):
if [[ -n "$topic" ]]; then
bash .claude/scripts/manage-topics.sh set "$next_num" "$topic" \
2>/dev/null || echo "Warning: manage-topics.sh set failed (non-fatal)" >&2
fi
The state.json update in Section 5.3 already writes the task data. TODO.md will be regenerated via generate-todo.sh in Section 5.5.
Regenerate TODO.md from state.json to reflect the newly linked artifact:
bash .claude/scripts/generate-todo.sh || echo "WARNING: generate-todo.sh failed (non-fatal)" >&2
git add specs/ .claude/
git commit -m "task ${next_num}: create and complete research
Session: ${session_id}"
Output to user:
## Project Overview Task Created
**Task #{N}**: Generate project-overview.md [RESEARCHED]
**Research artifact**: specs/{NNN}_{SLUG}/reports/01_project-overview-scan.md
The research artifact contains all scan findings and your responses. To generate the actual project-overview.md file:
1. Run `/plan {N}` to create an implementation plan
2. Run `/implement {N}` to generate the file
Alternatively, if you want to skip the plan step:
- Run `/implement {N} --force` to implement directly from the research