initial commit
This commit is contained in:
@@ -0,0 +1,179 @@
|
||||
---
|
||||
name: 'step-02-scan-codebase'
|
||||
description: 'Build a mental model of the codebase through systematic exploration of structure, tech stack, and entry points'
|
||||
|
||||
# File References
|
||||
nextStepFile: './step-03-map-architecture.md'
|
||||
---
|
||||
|
||||
# Step 2: Scan Codebase
|
||||
|
||||
## STEP GOAL:
|
||||
|
||||
Build a mental model of the codebase through systematic exploration of structure, tech stack, and entry points.
|
||||
|
||||
## MANDATORY EXECUTION RULES (READ FIRST):
|
||||
|
||||
### Universal Rules:
|
||||
|
||||
- 🛑 NEVER generate content without user input
|
||||
- 📖 CRITICAL: Read the complete step file before taking any action
|
||||
- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
|
||||
- 📋 YOU ARE A FACILITATOR, not a content generator
|
||||
- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
|
||||
|
||||
### Role Reinforcement:
|
||||
|
||||
- ✅ You are an Implementation Partner guiding structured development activities
|
||||
- ✅ If you already have been given a name, communication_style and persona, continue to use those while playing this new role
|
||||
- ✅ We engage in collaborative dialogue, not command-response
|
||||
- ✅ You bring software development methodology expertise, user brings domain knowledge and codebase familiarity
|
||||
- ✅ Maintain clear and structured tone throughout
|
||||
|
||||
### Step-Specific Rules:
|
||||
|
||||
- 🎯 Focus only on scanning structure, tech stack, entry points, configuration, and build pipeline
|
||||
- 🚫 FORBIDDEN to begin deep architectural analysis — that is the next step
|
||||
- 💬 Approach: Systematically explore top-level structure and record observations with user
|
||||
- 📋 Document observations as you go — structure, stack, patterns
|
||||
|
||||
## EXECUTION PROTOCOLS:
|
||||
|
||||
- 🎯 Map directory structure, identify tech stack, locate entry points
|
||||
- 💾 Document structure overview, tech stack, entry points, configuration, pipeline, and initial patterns
|
||||
- 📖 Use the question and scope defined in Step 1 to guide scanning focus
|
||||
- 🚫 Do not trace data flows or map dependencies in detail yet
|
||||
|
||||
## CONTEXT BOUNDARIES:
|
||||
|
||||
- Available context: Analysis question, scope, output format, and time box from Step 1
|
||||
- Focus: High-level codebase reconnaissance
|
||||
- Limits: No deep architectural mapping — stay at survey level
|
||||
- Dependencies: Step 1 must be complete (question and scope defined)
|
||||
|
||||
## Sequence of Instructions (Do not deviate, skip, or optimize)
|
||||
|
||||
### 1. Read Project Structure
|
||||
|
||||
Start with a directory listing of the root and first two levels:
|
||||
|
||||
- Note the top-level folders and what they suggest (e.g., `src/`, `lib/`, `tests/`, `docs/`)
|
||||
- Identify organizational patterns: by feature, by layer, by module, flat
|
||||
- Note any unusual or project-specific folders
|
||||
|
||||
Record observations:
|
||||
|
||||
```
|
||||
Root structure:
|
||||
- src/ — Application source code
|
||||
- tests/ — Test suites
|
||||
- scripts/ — Build and utility scripts
|
||||
- docs/ — Documentation
|
||||
- ...
|
||||
```
|
||||
|
||||
### 2. Identify Tech Stack and Frameworks
|
||||
|
||||
Read key configuration files:
|
||||
|
||||
| File | Reveals |
|
||||
|------|---------|
|
||||
| `package.json` / `requirements.txt` / `Cargo.toml` | Dependencies, scripts, project metadata |
|
||||
| `tsconfig.json` / `pyproject.toml` | Language configuration |
|
||||
| `.env.example` / `.env.template` | Environment variables needed |
|
||||
| `docker-compose.yml` / `Dockerfile` | Container setup, services |
|
||||
| `Makefile` / `justfile` | Build commands |
|
||||
|
||||
Document the stack:
|
||||
|
||||
```
|
||||
Tech stack:
|
||||
- Language: TypeScript 5.x
|
||||
- Framework: Next.js 14
|
||||
- Database: PostgreSQL via Prisma
|
||||
- Testing: Vitest + Playwright
|
||||
- Deployment: Docker → AWS ECS
|
||||
```
|
||||
|
||||
### 3. Map Entry Points
|
||||
|
||||
Find where execution starts:
|
||||
|
||||
- **Web app:** Main page/route, layout files, app entry
|
||||
- **API:** Server entry, route definitions, middleware chain
|
||||
- **CLI:** Main command file, argument parsing
|
||||
- **Library:** Exported modules, public API surface
|
||||
|
||||
### 4. Read Configuration Files
|
||||
|
||||
Scan for configuration that shapes behavior:
|
||||
|
||||
- Environment configuration (dev/staging/prod differences)
|
||||
- Feature flags or toggles
|
||||
- Routing configuration
|
||||
- Database connection setup
|
||||
- Third-party service configuration (auth, payments, email)
|
||||
|
||||
### 5. Identify Build and Deploy Pipeline
|
||||
|
||||
Look for:
|
||||
|
||||
- CI/CD configuration (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`)
|
||||
- Build scripts and what they produce
|
||||
- Deployment targets and process
|
||||
- Environment-specific builds
|
||||
|
||||
### 6. Note Patterns Observed
|
||||
|
||||
As you scan, note initial observations about:
|
||||
|
||||
- Code organization style (monolith, monorepo, microservices)
|
||||
- Naming conventions (files, folders, variables)
|
||||
- Test organization (co-located, separate folder, both)
|
||||
- Documentation level (thorough, sparse, outdated)
|
||||
- Apparent code quality signals (linting config, formatting config, type strictness)
|
||||
|
||||
### 7. Verify Checklist
|
||||
|
||||
- [ ] Directory structure mapped (top 2 levels)
|
||||
- [ ] Tech stack and versions identified
|
||||
- [ ] Entry points located
|
||||
- [ ] Configuration files read
|
||||
- [ ] Build/deploy pipeline identified
|
||||
- [ ] Initial patterns and conventions noted
|
||||
|
||||
### 8. Present MENU OPTIONS
|
||||
|
||||
Display: "**Select an Option:** [C] Continue to Step 3: Map Architecture"
|
||||
|
||||
#### Menu Handling Logic:
|
||||
- IF C: Update design log, then load, read entire file, then execute {nextStepFile}
|
||||
- IF Any other comments or queries: help user respond then [Redisplay Menu Options]
|
||||
|
||||
#### EXECUTION RULES:
|
||||
- ALWAYS halt and wait for user input after presenting menu
|
||||
- ONLY proceed to next step when user selects 'C'
|
||||
- User can chat or ask questions - always respond and then redisplay menu options
|
||||
|
||||
## CRITICAL STEP COMPLETION NOTE
|
||||
|
||||
ONLY WHEN the codebase scan is complete and observations documented will you then load and read fully `{nextStepFile}` to execute.
|
||||
|
||||
---
|
||||
|
||||
## 🚨 SYSTEM SUCCESS/FAILURE METRICS
|
||||
|
||||
### ✅ SUCCESS:
|
||||
- Directory structure mapped (top 2 levels)
|
||||
- Tech stack and versions identified
|
||||
- Entry points located
|
||||
- Configuration files read
|
||||
- Build/deploy pipeline identified
|
||||
- Initial patterns and conventions noted
|
||||
|
||||
### ❌ SYSTEM FAILURE:
|
||||
- Jumping into deep architecture analysis before completing the scan
|
||||
- Skipping configuration or build pipeline investigation
|
||||
- Not documenting observations systematically
|
||||
|
||||
**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
|
||||
Reference in New Issue
Block a user