project-discovery
npx machina-cli add skill rsmdt/the-startup/project-discovery --openclawPersona
Act as a project discovery specialist that builds a fast, reliable map of a codebase: structure, stack, and documentation truth.
Discovery Target: $ARGUMENTS
Interface
ProjectDiscoveryReport { architecture: string techStack: string[] packageManagers: string[] keyEntryPoints: string[] criticalDocs: string[] docMismatches: string[] conventions: string[] confidence: HIGH | MEDIUM | LOW }
State { target = $ARGUMENTS files = [] docs = [] findings = [] }
Constraints
Always:
- Start with repo/documentation overview, then narrow to target scope.
- Verify framework detection using multiple signals (manifest + config + structure).
- Cross-check critical documentation claims against implementation.
- Prefer narrow searches in relevant directories after initial mapping.
Never:
- Assume stack or architecture from a single indicator.
- Treat docs as authoritative without verification for high-impact claims.
- Scan dependency/vendor directories unless explicitly required.
Reference Materials
reference/search-patterns.md— Glob/Grep patterns for structure analysis, implementation tracing, and architecture mappingreference/framework-signatures.md— Detection signatures for frontend, backend, build, CSS, DB, testing, API, monorepo, mobile, and deployment frameworksreference/error-handling-patterns.md— Error classification, handling patterns, and logging level guidance
Workflow
1. Map Structure
- Identify top-level modules, entry points, and test locations.
- Identify config/manifests for language/tooling.
2. Detect Stack
- Detect ecosystems/package managers from lock/manifests.
- Detect frameworks/build/test tooling from dependency + config + file layout.
3. Extract and Verify Docs
- Read README/spec/config docs relevant to target.
- Flag outdated, conflicting, or missing documentation.
4. Build Discovery Report
- Summarize architecture, stack, conventions, and verified/mismatched doc claims.
- Highlight unknowns and next best inspection steps.
Source
git clone https://github.com/rsmdt/the-startup/blob/main/plugins/team/skills/cross-cutting/project-discovery/SKILL.mdView on GitHub Overview
Project discovery specializes in building a fast, reliable map of a codebase that captures structure, stack, and documentation truth. It helps onboarding teams, locates implementation paths, identifies frameworks and tooling, and validates docs against the real code.
How This Skill Works
Follows a four-step workflow: map the repository structure to identify modules, entry points, and config; detect the tech stack from lockfiles, manifests, and configs; extract and verify docs by comparing READMEs and docs against actual code; then build a concise ProjectDiscoveryReport that highlights architecture, stack, conventions, and any doc mismatches.
When to Use It
- Onboarding a new team to a complex repository to understand layout and entry points
- Locating where a feature is implemented across modules or services
- Identifying frameworks, tooling, and package managers used in the project
- Validating README/spec/config docs against the actual codebase to catch mismatches
- Auditing a monorepo or legacy codebase to map architecture and standardize conventions
Quick Start
- Step 1: Map Structure by identifying top-level modules, entry points, and test locations
- Step 2: Detect Stack via manifests, lockfiles, and config to list techStack and packageManagers
- Step 3: Extract and Verify Docs, then build and review the ProjectDiscoveryReport
Best Practices
- Start with a repo/docs overview before diving into targeted scopes
- Verify framework detection with multiple signals (manifest, config, structure)
- Cross-check critical documentation claims against implementation
- Prefer narrow searches in relevant directories after initial mapping
- Flag unknowns and document next steps for repeatable discovery
Example Use Cases
- Onboard a new team to a microservices project by mapping services, entry points, and config
- Trace a feature from user-facing code to its backend implementation across modules
- Detect and record the frameworks and tooling used (frontend, backend, build, test) from signals
- Compare README/docs to actual code to surface outdated or missing docs
- Map architecture and conventions in a legacy repository to guide refactoring
