|
1 | 1 | --- |
2 | | -description: "Analyze a project's tech stack including languages, frameworks, runtimes, package managers, and dependencies using the Syncable CLI sync-ctl tool" |
| 2 | +description: "Use when the user asks to analyze a project, understand the tech stack, detect frameworks, check what languages are used, identify runtimes or package managers, or as a first step before security/vulnerability scans" |
3 | 3 | --- |
4 | 4 |
|
5 | | -## Purpose |
| 5 | +## Overview |
6 | 6 |
|
7 | | -Analyze a project directory to detect its tech stack: programming languages, frameworks, runtimes, package managers, dependencies, Docker presence, and monorepo structure. This is the foundation skill — most workflows start here to understand what they're working with. |
| 7 | +Detect a project's tech stack — languages, frameworks, runtimes, package managers, dependencies, Docker presence, monorepo structure. Foundation command; most workflows start here. |
8 | 8 |
|
9 | | -## Prerequisites |
| 9 | +## Quick Reference |
10 | 10 |
|
11 | | -- `sync-ctl` binary installed and on PATH |
12 | | -- Agent has access to the project directory |
| 11 | +| Flag | Purpose | |
| 12 | +|------|---------| |
| 13 | +| `--agent` | Compressed output for agent consumption (always use) | |
| 14 | +| `--display {matrix\|detailed\|summary}` | Human-readable format | |
| 15 | +| `--only <filters>` | Comma-separated: `languages`, `frameworks`, `dependencies` | |
13 | 16 |
|
14 | | -## Commands |
| 17 | +## Steps |
15 | 18 |
|
16 | | -### Basic analysis (agent output) |
| 19 | +### 1. Run analysis |
17 | 20 |
|
18 | 21 | ```bash |
19 | 22 | sync-ctl analyze <PATH> --agent |
20 | 23 | ``` |
21 | 24 |
|
22 | | -### Human-readable matrix view |
23 | | - |
24 | | -```bash |
25 | | -sync-ctl analyze <PATH> --display matrix |
26 | | -``` |
27 | | - |
28 | | -### Filtered analysis (only specific aspects) |
29 | | - |
30 | | -```bash |
31 | | -sync-ctl analyze <PATH> --agent --only languages,frameworks |
32 | | -sync-ctl analyze <PATH> --agent --only dependencies |
33 | | -``` |
34 | | - |
35 | | -### Key Flags |
36 | | - |
37 | | -| Flag | Purpose | |
38 | | -|------|---------| |
39 | | -| `--agent` | Compressed output for agent consumption (always use when processing results) | |
40 | | -| `--detailed` | Show detailed analysis (legacy vertical format) | |
41 | | -| `--display {matrix\|detailed\|summary}` | Display format for human-readable output | |
42 | | -| `--only <filters>` | Comma-separated: `languages`, `frameworks`, `dependencies` | |
43 | | - |
44 | | -## Output Interpretation |
| 25 | +**Success criteria:** JSON output with `summary` and `full_data_ref` fields present. |
45 | 26 |
|
46 | | -When reporting to the user, prioritize: primary language, main framework, runtime version, and whether Docker/K8s infrastructure exists. |
| 27 | +### 2. Report to user |
47 | 28 |
|
48 | | -## Reading Results |
| 29 | +Prioritize: primary language, main framework, runtime version, Docker/K8s presence. |
49 | 30 |
|
50 | | -When you use `--agent`, the output is a compressed summary — not the full analysis. Act on it directly for most decisions. |
| 31 | +### 3. Drill into details (if needed) |
51 | 32 |
|
52 | | -The output JSON includes: |
53 | | -- `summary` — project count, languages, frameworks detected |
54 | | -- `full_data_ref` — reference ID for retrieving full data |
55 | | -- `retrieval_hint` — exact command to get more details |
| 33 | +Save the `full_data_ref`. Use `sync-ctl retrieve` — do NOT re-run analyze: |
56 | 34 |
|
57 | | -To drill into specifics: |
58 | 35 | ```bash |
59 | | -# Get framework details |
60 | 36 | sync-ctl retrieve <ref_id> --query "section:frameworks" |
61 | | - |
62 | | -# Get language breakdown |
63 | 37 | sync-ctl retrieve <ref_id> --query "section:languages" |
64 | | - |
65 | | -# Get specific project details (monorepos) |
66 | | -sync-ctl retrieve <ref_id> --query "project:<project-name>" |
67 | | - |
68 | | -# Get specific language details |
| 38 | +sync-ctl retrieve <ref_id> --query "project:<name>" # monorepos |
69 | 39 | sync-ctl retrieve <ref_id> --query "language:Go" |
70 | | - |
71 | | -# Get specific framework details |
72 | 40 | sync-ctl retrieve <ref_id> --query "framework:React" |
73 | | - |
74 | | -# List all stored outputs |
75 | | -sync-ctl retrieve --list |
76 | 41 | ``` |
77 | 42 |
|
78 | | -**Available query filters:** `section:summary`, `section:frameworks`, `section:languages`, `language:<name>`, `framework:<name>`, `project:<name>`, `compact:true` |
| 43 | +**Available queries:** `section:summary`, `section:frameworks`, `section:languages`, `language:<name>`, `framework:<name>`, `project:<name>`, `compact:true` |
79 | 44 |
|
80 | 45 | ## Error Handling |
81 | 46 |
|
82 | | -| Error | Cause | Action | |
83 | | -|-------|-------|--------| |
84 | | -| `No such file or directory` | Invalid path | Ask user to verify the project path | |
85 | | -| Empty output | No recognizable project files | Tell user the directory may not contain a supported project. Run `sync-ctl support` to show supported technologies | |
86 | | -| Timeout | Very large monorepo | Try `--only languages` for a faster partial scan | |
87 | | - |
88 | | -## Examples |
89 | | - |
90 | | -**Analyze current directory:** |
91 | | -```bash |
92 | | -sync-ctl analyze . --agent |
93 | | -``` |
94 | | - |
95 | | -**Analyze a specific project:** |
96 | | -```bash |
97 | | -sync-ctl analyze /path/to/project --agent |
98 | | -``` |
99 | | - |
100 | | -**Quick language-only check:** |
101 | | -```bash |
102 | | -sync-ctl analyze . --agent --only languages |
103 | | -``` |
| 47 | +| Error | Action | |
| 48 | +|-------|--------| |
| 49 | +| `No such file or directory` | Ask user to verify path | |
| 50 | +| Empty output | No supported project files. Run `sync-ctl support` | |
| 51 | +| Timeout on large monorepo | Try `--only languages` for partial scan | |
0 commit comments