agileflow 4.0.0-alpha.6 → 4.0.0-alpha.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/content/plugins/ads/skills/agileflow-ads/workflows/audit.md +90 -36
- package/content/plugins/ads/skills/agileflow-ads/workflows/generate.md +57 -26
- package/content/plugins/core/hooks/damage-control-patterns.yaml +1 -1
- package/content/plugins/seo/skills/agileflow-seo/workflows/audit.md +77 -41
- package/content/plugins/seo/skills/agileflow-seo/workflows/page.md +40 -23
- package/package.json +1 -1
- package/src/runtime/ide/codex-config.js +5 -6
- package/src/runtime/installer/install.js +17 -5
- package/src/runtime/skills/learnings.js +2 -0
|
@@ -2,63 +2,117 @@
|
|
|
2
2
|
|
|
3
3
|
**Triggers:** "audit my ads", "run an ads audit", "review my Google Ads", "check my Meta campaigns", "ads health score", "what's wrong with my advertising"
|
|
4
4
|
|
|
5
|
-
**Goal:** Deploy 6 specialized advertising analyzers in parallel against the user's
|
|
5
|
+
**Goal:** Deploy 6 specialized advertising analyzers in parallel against the user's account data, synthesize results into a weighted Ads Health Score (0–100), and produce a prioritized action plan with specific, dollar-impact estimates where possible.
|
|
6
6
|
|
|
7
7
|
## Inputs needed
|
|
8
8
|
|
|
9
|
-
| Input
|
|
10
|
-
|
|
|
11
|
-
| account data
|
|
12
|
-
|
|
|
13
|
-
|
|
|
9
|
+
| Input | Required | How to get it |
|
|
10
|
+
| ---------------------- | -------- | ---------------------------------------------------------- |
|
|
11
|
+
| account data | Yes | CSV export, pasted table, or described setup |
|
|
12
|
+
| platform(s) | No | Auto-detect from data, or already captured in opening flow |
|
|
13
|
+
| industry + KPI targets | No | Ask conversationally — changes benchmarks significantly |
|
|
14
14
|
|
|
15
15
|
## Steps
|
|
16
16
|
|
|
17
|
-
1.
|
|
17
|
+
1. **If account data is not provided**, ask specifically — don't make them guess what format to use:
|
|
18
|
+
|
|
19
|
+
```xml
|
|
20
|
+
<invoke name="AskUserQuestion">
|
|
21
|
+
<parameter name="questions">[{
|
|
22
|
+
"question": "To audit your account, I need your campaign data. What's easiest?",
|
|
23
|
+
"header": "Account data",
|
|
24
|
+
"multiSelect": false,
|
|
25
|
+
"options": [
|
|
26
|
+
{"label": "Paste a CSV export (Recommended)", "description": "Google Ads: Campaigns tab → Download. Meta: Ads Manager → Columns → Export. Even a partial export works."},
|
|
27
|
+
{"label": "Paste the performance table from your dashboard", "description": "Copy/paste the text from your campaigns view — I'll parse it"},
|
|
28
|
+
{"label": "Describe your setup", "description": "Tell me: platforms, monthly spend, ROAS/CPA, campaign types, and main goals"},
|
|
29
|
+
{"label": "I have a file — share the path", "description": "Point me to an exported CSV and I'll read it directly"}
|
|
30
|
+
]
|
|
31
|
+
}]</parameter>
|
|
32
|
+
</invoke>
|
|
33
|
+
```
|
|
18
34
|
|
|
19
|
-
2.
|
|
35
|
+
2. **Gather context** — ask conversationally before running analyzers:
|
|
36
|
+
- Industry / vertical (e-commerce, SaaS, local services, lead gen, B2B?)
|
|
37
|
+
- Monthly ad spend range
|
|
38
|
+
- Primary KPI: ROAS target, CPA target, or lead volume goal?
|
|
39
|
+
- How long have these campaigns been running?
|
|
20
40
|
|
|
21
|
-
|
|
41
|
+
These change benchmarks significantly. A 3x ROAS for e-commerce is average; for SaaS it's strong. Skip if already captured in the opening flow.
|
|
22
42
|
|
|
23
|
-
|
|
43
|
+
3. **Detect active platforms** from the data. If the user specified platforms in the opening flow, use those.
|
|
24
44
|
|
|
25
|
-
|
|
26
|
-
- **Google analyzer** — campaign structure, keyword strategy, quality scores, ad copy (74 checks)
|
|
27
|
-
- **Meta analyzer** — audience targeting, creative fatigue,
|
|
28
|
-
- **Budget analyzer** — spend distribution,
|
|
29
|
-
- **Creative analyzer** —
|
|
45
|
+
4. **Deploy all 6 analyzers simultaneously** — no need to ask for depth, run quick by default:
|
|
46
|
+
- **Google analyzer** — campaign structure, keyword strategy, quality scores, ad copy, wasted spend (74 checks)
|
|
47
|
+
- **Meta analyzer** — audience targeting, creative fatigue, objectives, pixel/CAPI setup (46 checks)
|
|
48
|
+
- **Budget analyzer** — spend distribution, scaling rules, bid strategy efficiency (24 checks)
|
|
49
|
+
- **Creative analyzer** — copy quality, CTR patterns, creative fatigue, A/B test coverage
|
|
30
50
|
- **Tracking analyzer** — pixel/tag setup, conversion tracking accuracy, attribution model
|
|
31
51
|
- **Compliance analyzer** — policy violations, restricted content, account health flags
|
|
32
52
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
53
|
+
5. **Apply quality gates automatically:**
|
|
54
|
+
- Flag if tracking is broken — optimization recommendations are unreliable without it
|
|
55
|
+
- Apply 3x Kill Rule: campaigns with CPA > 3x target for 2+ weeks → flag for pause
|
|
56
|
+
- Flag Broad Match keywords without Smart Bidding
|
|
57
|
+
- Flag recent changes that may have reset learning phase
|
|
58
|
+
|
|
59
|
+
6. **Weighted scoring:** Tracking 25%, Wasted Spend 20%, Structure 15%, Creative 15%, Budget 15%, Compliance 10%.
|
|
60
|
+
|
|
61
|
+
7. **Present the Ads Health Score (0–100):**
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
Ads Health Score: 61/100 — needs work
|
|
65
|
+
|
|
66
|
+
Category Score Top Issue
|
|
67
|
+
Tracking 45 Google conversion tag missing on /checkout
|
|
68
|
+
Wasted Spend 52 4 campaigns at 4-6x target CPA — $3,200/mo estimated waste
|
|
69
|
+
Structure 74 7 ad groups with single ads — no rotation testing
|
|
70
|
+
Creative 68 Meta creative sets showing 90%+ impression share (fatigue)
|
|
71
|
+
Budget 71 3 campaigns in learning phase — avoid budget changes
|
|
72
|
+
Compliance 90 —
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
8. **Prioritized action plan:**
|
|
76
|
+
- **P0** (immediate blockers): Broken tracking, policy violations, campaigns burning budget with zero conversions
|
|
77
|
+
- **P1** (high ROI quick wins): Kill Rule candidates, wasted spend, broken attribution
|
|
78
|
+
- **P2** (structural improvements): Campaign organization, bidding strategy, audience targeting
|
|
79
|
+
- **P3** (creative and testing): Copy refresh, A/B test setup, creative rotation
|
|
80
|
+
|
|
81
|
+
9. **Guide next step with AskUserQuestion** — specific to actual findings:
|
|
82
|
+
|
|
83
|
+
```xml
|
|
84
|
+
<invoke name="AskUserQuestion">
|
|
85
|
+
<parameter name="questions">[{
|
|
86
|
+
"question": "Ads Health Score: {X}/100. {p0_count} immediate blockers, {p1_count} high-ROI quick wins. Biggest issue: {top_finding}.",
|
|
87
|
+
"header": "What to fix first",
|
|
88
|
+
"multiSelect": false,
|
|
89
|
+
"options": [
|
|
90
|
+
{"label": "Fix {top_p0_issue} now (Recommended)", "description": "{specific fix — e.g., 'Add Google conversion tag to /checkout — without this, all ROAS data is wrong'}"},
|
|
91
|
+
{"label": "Pause {n} campaigns failing the 3x Kill Rule", "description": "{specific campaigns} spending {estimated_waste}/mo with {n} conversions — cut waste before optimizing"},
|
|
92
|
+
{"label": "Deep-dive into {lowest_category} ({score}/100)", "description": "Worst area — I'll walk through every finding with specific fixes"},
|
|
93
|
+
{"label": "Generate fresh ad copy to test against current", "description": "40+ headline/body/CTA variants for your top campaigns — use existing copy as the baseline"}
|
|
94
|
+
]
|
|
95
|
+
}]</parameter>
|
|
96
|
+
</invoke>
|
|
97
|
+
```
|
|
42
98
|
|
|
43
|
-
|
|
99
|
+
Customize every option. Don't show kill rule option if no campaigns qualify. Don't show copy generation if they just came from the generate workflow.
|
|
44
100
|
|
|
45
101
|
## Output
|
|
46
102
|
|
|
47
|
-
Ads Health Score with weighted category scores. Prioritized action plan
|
|
103
|
+
Ads Health Score (0–100) with weighted category scores. Prioritized action plan (P0–P3). Platform-specific findings. Estimated wasted spend where calculable. Baseline for future audits.
|
|
48
104
|
|
|
49
105
|
## Fallbacks
|
|
50
106
|
|
|
51
|
-
**If
|
|
52
|
-
Present options as a numbered list
|
|
107
|
+
**If AskUserQuestion is unavailable:**
|
|
108
|
+
Present options as a numbered list. Example:
|
|
53
109
|
|
|
54
110
|
```
|
|
55
|
-
|
|
56
|
-
1. Fix the P0
|
|
57
|
-
2.
|
|
58
|
-
3.
|
|
111
|
+
What would you like to tackle first?
|
|
112
|
+
1. Fix the P0 issues now
|
|
113
|
+
2. Pause the Kill Rule campaigns
|
|
114
|
+
3. Deep-dive into the worst category
|
|
59
115
|
```
|
|
60
116
|
|
|
61
|
-
**If agent spawning
|
|
62
|
-
|
|
63
|
-
Work through the key checks for each domain yourself using the reference files in `references/`.
|
|
64
|
-
Consolidate findings into the same structured output format — the user gets the same result, just slower.
|
|
117
|
+
**If agent spawning is unavailable:**
|
|
118
|
+
Run each analysis inline sequentially using the reference files in `references/`. Consolidate into the same output format — same result, just slower.
|
|
@@ -6,48 +6,79 @@
|
|
|
6
6
|
|
|
7
7
|
## Inputs needed
|
|
8
8
|
|
|
9
|
-
| Input | Required | How to get it
|
|
10
|
-
| ------------------- | -------- |
|
|
11
|
-
| product description | Yes | Ask
|
|
12
|
-
| target platform | No |
|
|
13
|
-
| variant count | No | Default: 40
|
|
14
|
-
| ICP angles | No |
|
|
9
|
+
| Input | Required | How to get it |
|
|
10
|
+
| ------------------- | -------- | ------------------------------------------------------------------- |
|
|
11
|
+
| product description | Yes | Ask for it if not provided |
|
|
12
|
+
| target platform | No | Already captured in opening flow — use that. Ask only if not known. |
|
|
13
|
+
| variant count | No | Default: 40. Ask only if they want a different number. |
|
|
14
|
+
| ICP angles | No | Auto-detect 5 from product description, then confirm |
|
|
15
15
|
|
|
16
16
|
## Steps
|
|
17
17
|
|
|
18
|
-
1. If product description is not provided
|
|
18
|
+
1. **If product description is not provided**, ask: _"What are you advertising? Paste your product description, landing page URL, or existing ad copy — I'll work from any of those."_ Accept any format.
|
|
19
19
|
|
|
20
|
-
2.
|
|
20
|
+
2. **Don't re-ask about platform** if already captured in the opening flow. Use what you know. Only ask if platform is genuinely unknown:
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
_"Which platform should I optimize the format for? (or I can generate for all)"_
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
3. **Auto-detect 5 ICP angles** from the product description. Common angles:
|
|
25
|
+
- Pain-point-led: leads with the problem they're experiencing
|
|
26
|
+
- Outcome-focused: leads with the transformation or result
|
|
27
|
+
- Social-proof: authority, users, case studies
|
|
28
|
+
- Urgency/FOMO: time limit, scarcity, risk of inaction
|
|
29
|
+
- Feature-differentiated: specific capability competitors don't have
|
|
25
30
|
|
|
26
|
-
5.
|
|
27
|
-
- **Headlines** (Google: max 30 chars; Meta: up to 40 chars): problem-aware, solution-aware, benefit-led
|
|
28
|
-
- **Body copy** (short: 1–2 sentences; long: 3–4 sentences): matches each headline angle
|
|
29
|
-
- **CTAs** (6–8 variants): action-oriented, urgency, curiosity
|
|
31
|
+
Show the angles and ask: _"I detected these 5 angles: [list]. Any you want to add or swap out?"_ Keep it conversational — if they say "looks good", move on immediately.
|
|
30
32
|
|
|
31
|
-
|
|
33
|
+
4. **Generate variants for each angle × each format:**
|
|
32
34
|
|
|
33
|
-
|
|
34
|
-
-
|
|
35
|
-
-
|
|
35
|
+
**Headlines:**
|
|
36
|
+
- Google: max 30 characters — problem-aware, solution-aware, benefit-led variants
|
|
37
|
+
- Meta: up to 40 characters — hook-first, curiosity-driven variants
|
|
38
|
+
- LinkedIn: professional tone, outcome-focused
|
|
36
39
|
|
|
37
|
-
|
|
40
|
+
**Body copy:**
|
|
41
|
+
- Short (1–2 sentences): matches headline angle, drives to CTA
|
|
42
|
+
- Long (3–4 sentences): expands on the angle with a proof point
|
|
43
|
+
|
|
44
|
+
**CTAs** (6–8 variants): action-oriented, urgency, curiosity — varied by platform norms
|
|
45
|
+
|
|
46
|
+
5. **Show the variants** as structured markdown organized by angle and format, with counts. Make them scannable — the user needs to read and react quickly.
|
|
47
|
+
|
|
48
|
+
6. **Generate platform-ready export files:**
|
|
49
|
+
- **Meta bulk upload CSV**: Campaign / Ad Set / Ad columns with all variants
|
|
50
|
+
- **Google Ads Editor format**: Campaign / Ad Group / Headline1–15 / Description1–4
|
|
51
|
+
|
|
52
|
+
7. **Guide next step with AskUserQuestion** — specific to what was generated:
|
|
53
|
+
|
|
54
|
+
```xml
|
|
55
|
+
<invoke name="AskUserQuestion">
|
|
56
|
+
<parameter name="questions">[{
|
|
57
|
+
"question": "{N} variants generated across {angle_count} ICP angles. Top recommended variants to test first: {top_3_variants}.",
|
|
58
|
+
"header": "What's next",
|
|
59
|
+
"multiSelect": false,
|
|
60
|
+
"options": [
|
|
61
|
+
{"label": "Save the platform CSV and wrap up (Recommended)", "description": "Export is ready — {platform} format with all {N} variants"},
|
|
62
|
+
{"label": "Regenerate the {weakest_angle} angle", "description": "That angle produced the weakest variants — I'll try different formulas"},
|
|
63
|
+
{"label": "Create A/B test pairs from the top 5 variants", "description": "Pair your strongest variants for head-to-head testing — one variable changed per pair"},
|
|
64
|
+
{"label": "Audit existing campaigns before launching these", "description": "Make sure tracking is working before investing in new copy — /agileflow:ads:track"}
|
|
65
|
+
]
|
|
66
|
+
}]</parameter>
|
|
67
|
+
</invoke>
|
|
68
|
+
```
|
|
38
69
|
|
|
39
70
|
## Output
|
|
40
71
|
|
|
41
|
-
Structured markdown with all variants organized by angle. Platform-ready CSV file(s). Total variant count
|
|
72
|
+
Structured markdown with all variants organized by angle and format. Platform-ready CSV file(s). Total variant count. Recommended top 5 variants to test first based on formula strength.
|
|
42
73
|
|
|
43
74
|
## Fallbacks
|
|
44
75
|
|
|
45
|
-
**If
|
|
46
|
-
Present options as a numbered list
|
|
76
|
+
**If AskUserQuestion is unavailable:**
|
|
77
|
+
Present options as a numbered list. Example:
|
|
47
78
|
|
|
48
79
|
```
|
|
49
|
-
|
|
50
|
-
1. Save and
|
|
51
|
-
2.
|
|
52
|
-
3.
|
|
80
|
+
What would you like to do next?
|
|
81
|
+
1. Save the CSV and wrap up
|
|
82
|
+
2. Regenerate a specific angle
|
|
83
|
+
3. Create A/B test pairs
|
|
53
84
|
```
|
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
|
|
16
16
|
patterns:
|
|
17
17
|
# --- Catastrophic filesystem operations ---
|
|
18
|
-
- regex: 'rm\s+-[a-zA-Z]*r[a-zA-Z]*f[a-zA-Z]*\s+(/|~|\$HOME)\
|
|
18
|
+
- regex: 'rm\s+-[a-zA-Z]*r[a-zA-Z]*f[a-zA-Z]*\s+(/|~|\$HOME)(\s|$)'
|
|
19
19
|
kind: bash
|
|
20
20
|
severity: error
|
|
21
21
|
reason: rm -rf on / or $HOME is almost certainly a mistake — refuse outright
|
|
@@ -2,61 +2,97 @@
|
|
|
2
2
|
|
|
3
3
|
**Triggers:** "run an SEO audit", "audit my website for SEO", "what are my SEO issues", "SEO health score", "check SEO for example.com", "full SEO review"
|
|
4
4
|
|
|
5
|
-
**Goal:** Deploy 6 SEO analyzers in parallel against a website, synthesize results into a weighted health score (0–100), and produce a prioritized action plan.
|
|
5
|
+
**Goal:** Deploy 6 SEO analyzers in parallel against a website, synthesize results into a weighted health score (0–100), and produce a prioritized action plan with specific, actionable fixes.
|
|
6
6
|
|
|
7
7
|
## Inputs needed
|
|
8
8
|
|
|
9
|
-
| Input | Required | How to get it
|
|
10
|
-
| --------- | -------- |
|
|
11
|
-
| URL | Yes | Ask
|
|
12
|
-
|
|
|
13
|
-
|
|
|
9
|
+
| Input | Required | How to get it |
|
|
10
|
+
| --------- | -------- | --------------------------------------------------------------------- |
|
|
11
|
+
| URL | Yes | Ask for it if not provided |
|
|
12
|
+
| site type | No | Auto-detect from homepage, or already captured in opening flow |
|
|
13
|
+
| context | No | Traffic level, recent changes, target keywords — ask conversationally |
|
|
14
14
|
|
|
15
15
|
## Steps
|
|
16
16
|
|
|
17
|
-
1.
|
|
18
|
-
|
|
19
|
-
2.
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
- **
|
|
28
|
-
- **
|
|
29
|
-
- **
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
17
|
+
1. **If URL is not provided**, ask: _"What's the URL? I'll fetch your site and start the analysis."_ Accept homepage or any page. Don't offer fake options for this — just ask for the URL.
|
|
18
|
+
|
|
19
|
+
2. **Gather context** (2-3 questions, conversational not interrogation):
|
|
20
|
+
- _"Roughly how much organic traffic does the site get per month? And have you made any big changes recently — migration, redesign, new CMS?"_ — traffic level affects prioritization, recent changes are the #1 cause of drops
|
|
21
|
+
- If they have target keywords: _"Any specific pages or keywords you want me to focus on?"_
|
|
22
|
+
- Skip these if they already answered in the opening flow
|
|
23
|
+
|
|
24
|
+
3. **Fetch the homepage** to detect site type (e-commerce, SaaS, local business, publisher, etc.) if not already known. Also fetch `robots.txt` and `sitemap.xml`.
|
|
25
|
+
|
|
26
|
+
4. **Deploy all 6 analyzers simultaneously** — default to quick depth, no need to ask:
|
|
27
|
+
- **Technical** — crawlability, indexability, HTTPS, redirects, canonical tags, mobile viewport, Core Web Vitals indicators
|
|
28
|
+
- **Content** — title tags, meta descriptions, heading structure, content quality, E-E-A-T signals, word count by page type
|
|
29
|
+
- **Schema** — structured data presence, correct schema types for detected business type, markup validity
|
|
30
|
+
- **Performance** — page speed signals, LCP, CLS, FID, render-blocking resources
|
|
31
|
+
- **Images** — alt text coverage, file sizes, next-gen formats (WebP/AVIF), lazy loading
|
|
32
|
+
- **Sitemap** — presence, coverage, freshness, consistency with robots.txt
|
|
33
|
+
|
|
34
|
+
5. **Apply business-type-specific benchmarks.** E-commerce needs Product schema; local business needs LocalBusiness schema; publisher needs Article schema and E-E-A-T signals.
|
|
35
|
+
|
|
36
|
+
6. **Weighted scoring:** Technical 20%, Content 20%, Schema 15%, Performance 15%, Images 15%, Sitemap 15%.
|
|
37
|
+
|
|
38
|
+
7. **Present the SEO Health Score (0–100)** with category breakdown:
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
Site: example.com
|
|
42
|
+
Business type: SaaS
|
|
43
|
+
|
|
44
|
+
Category Score Top Issue
|
|
45
|
+
Technical 61 12 pages missing canonical tags
|
|
46
|
+
Content 74 Meta descriptions missing on 8 pages
|
|
47
|
+
Schema 45 No structured data found — rich results blocked
|
|
48
|
+
Performance 82 LCP 3.1s — above 2.5s threshold
|
|
49
|
+
Images 58 31 images missing alt text
|
|
50
|
+
Sitemap 90 —
|
|
51
|
+
|
|
52
|
+
Overall: 68/100 — needs work
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
8. **Prioritized action plan:**
|
|
56
|
+
- **P0** (score < 60 or blocking issue): Fix immediately — indexing, canonical, noindex errors
|
|
57
|
+
- **P1** (quick wins): High ROI, low effort — missing schema, alt text, meta descriptions
|
|
58
|
+
- **P2** (structural): Performance, content depth, E-E-A-T signals
|
|
59
|
+
- **P3** (fine-tuning): Sitemap freshness, internal linking optimization
|
|
60
|
+
|
|
61
|
+
9. **Guide next step with AskUserQuestion** — make it specific to actual findings:
|
|
62
|
+
|
|
63
|
+
```xml
|
|
64
|
+
<invoke name="AskUserQuestion">
|
|
65
|
+
<parameter name="questions">[{
|
|
66
|
+
"question": "Audit complete. {site} scored {X}/100 — {critical} critical issues, {high} high. Biggest blocker: {top_issue}.",
|
|
67
|
+
"header": "What to tackle",
|
|
68
|
+
"multiSelect": false,
|
|
69
|
+
"options": [
|
|
70
|
+
{"label": "Fix {top_p0_issue} now (Recommended)", "description": "{specific fix + expected impact, e.g. 'Add canonical tags to 12 pages — prevents Google from choosing the wrong version to rank'}"},
|
|
71
|
+
{"label": "Generate {missing_schema_type} JSON-LD markup", "description": "I'll produce copy-paste structured data for your {page_type} — takes 2 minutes to add"},
|
|
72
|
+
{"label": "Deep-dive into {lowest_category} ({score}/100)", "description": "Worst area — I'll give you implementation-ready fixes for every finding"},
|
|
73
|
+
{"label": "Analyze a specific page in depth", "description": "6-dimension report card on your most important page — homepage, pricing, or top landing page"}
|
|
74
|
+
]
|
|
75
|
+
}]</parameter>
|
|
76
|
+
</invoke>
|
|
77
|
+
```
|
|
40
78
|
|
|
41
|
-
|
|
79
|
+
Customize every option — don't show schema option if schema scored 90+. Don't show the page analysis if they specifically said they want site-wide fixes.
|
|
42
80
|
|
|
43
81
|
## Output
|
|
44
82
|
|
|
45
|
-
SEO Health Score (0–100) with
|
|
83
|
+
SEO Health Score (0–100) with per-category scores. Prioritized action plan (P0–P3). Business-type-specific recommendations. Baseline for tracking improvement over time.
|
|
46
84
|
|
|
47
85
|
## Fallbacks
|
|
48
86
|
|
|
49
|
-
**If
|
|
50
|
-
Present options as a numbered list
|
|
87
|
+
**If AskUserQuestion is unavailable:**
|
|
88
|
+
Present options as a numbered list. Example:
|
|
51
89
|
|
|
52
90
|
```
|
|
53
|
-
|
|
54
|
-
1. Fix the P0
|
|
55
|
-
2.
|
|
56
|
-
3.
|
|
91
|
+
What would you like to tackle first?
|
|
92
|
+
1. Fix the P0 issues now
|
|
93
|
+
2. Generate missing schema markup
|
|
94
|
+
3. Deep-dive into the lowest-scoring category
|
|
57
95
|
```
|
|
58
96
|
|
|
59
|
-
**If agent spawning
|
|
60
|
-
|
|
61
|
-
Work through the key checks for each domain yourself using the reference files in `references/`.
|
|
62
|
-
Consolidate findings into the same structured output format — the user gets the same result, just slower.
|
|
97
|
+
**If agent spawning is unavailable:**
|
|
98
|
+
Run each analysis inline sequentially using the reference files in `references/`. Consolidate into the same output format — same result, just slower.
|
|
@@ -2,22 +2,23 @@
|
|
|
2
2
|
|
|
3
3
|
**Triggers:** "analyze this page for SEO", "check the SEO on /about", "deep SEO analysis for this URL", "is this page optimized", "on-page SEO for example.com/product", "why isn't this page ranking"
|
|
4
4
|
|
|
5
|
-
**Goal:**
|
|
5
|
+
**Goal:** Deep, scored analysis of a single page across 6 SEO dimensions — produces a report card with specific, copy-paste-ready fixes ordered by impact.
|
|
6
6
|
|
|
7
7
|
## Inputs needed
|
|
8
8
|
|
|
9
|
-
| Input
|
|
10
|
-
|
|
|
11
|
-
| URL
|
|
12
|
-
|
|
|
9
|
+
| Input | Required | How to get it |
|
|
10
|
+
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
|
|
11
|
+
| URL | Yes | Ask for it if not provided |
|
|
12
|
+
| target keyword | No | Ask: "What keyword are you trying to rank this page for?" — changes relevance scoring |
|
|
13
|
+
| context | No | "Why are you analyzing this page?" — surfaces whether it's a ranking drop, pre-launch review, or optimization |
|
|
13
14
|
|
|
14
15
|
## Steps
|
|
15
16
|
|
|
16
|
-
1.
|
|
17
|
+
1. **If URL is not provided**, ask: _"Which page URL should I analyze?"_ If they say the page isn't ranking, also ask: _"What keyword are you trying to rank it for?"_ — this context changes every recommendation.
|
|
17
18
|
|
|
18
|
-
2. Fetch the page
|
|
19
|
+
2. **Fetch the page.** Check HTTP status, response time, HTTPS. Extract full HTML. If the page returns non-200, diagnose the status code issue before proceeding.
|
|
19
20
|
|
|
20
|
-
3. Analyze
|
|
21
|
+
3. **Analyze all 6 dimensions:**
|
|
21
22
|
|
|
22
23
|
**On-Page SEO**
|
|
23
24
|
- Title tag: present? 30–60 chars? keyword-forward? unique?
|
|
@@ -37,8 +38,7 @@
|
|
|
37
38
|
- AI citation readiness: 134–167 word structured blocks
|
|
38
39
|
|
|
39
40
|
**Technical**
|
|
40
|
-
- HTTP status code
|
|
41
|
-
- Response time / TTFB
|
|
41
|
+
- HTTP status code and response time / TTFB
|
|
42
42
|
- Mobile viewport configured
|
|
43
43
|
- Robots directives (index/noindex)
|
|
44
44
|
- Structured data presence
|
|
@@ -62,12 +62,13 @@
|
|
|
62
62
|
- Unminified JS/CSS
|
|
63
63
|
- Missing compression signals
|
|
64
64
|
|
|
65
|
-
4. Score each dimension 0–100
|
|
65
|
+
4. **Score each dimension 0–100.** Thresholds: 90+ excellent, 75–89 good, 60–74 needs work, below 60 critical.
|
|
66
66
|
|
|
67
|
-
5. Present the report card
|
|
67
|
+
5. **Present the report card:**
|
|
68
68
|
|
|
69
69
|
```
|
|
70
|
-
Page:
|
|
70
|
+
Page: example.com/pricing
|
|
71
|
+
Target keyword: project management software
|
|
71
72
|
|
|
72
73
|
Dimension Score Top Issue
|
|
73
74
|
On-Page SEO 84 H1 missing target keyword
|
|
@@ -80,22 +81,38 @@
|
|
|
80
81
|
Overall: 72/100
|
|
81
82
|
```
|
|
82
83
|
|
|
83
|
-
6. List specific fixes ordered by impact
|
|
84
|
-
|
|
85
|
-
7.
|
|
84
|
+
6. **List specific fixes ordered by impact** — critical issues first, then quick wins, then fine-tuning. For each fix, include the exact change needed (not just "fix the H1" — say "Change H1 from 'Our Pricing Plans' to 'Project Management Software — Pricing'").
|
|
85
|
+
|
|
86
|
+
7. **Guide next step with AskUserQuestion:**
|
|
87
|
+
|
|
88
|
+
```xml
|
|
89
|
+
<invoke name="AskUserQuestion">
|
|
90
|
+
<parameter name="questions">[{
|
|
91
|
+
"question": "{page} scored {X}/100. {top_issue} is the biggest drag. Here's what to fix first:",
|
|
92
|
+
"header": "Next action",
|
|
93
|
+
"multiSelect": false,
|
|
94
|
+
"options": [
|
|
95
|
+
{"label": "Fix {top_issue} now (Recommended)", "description": "{exact change needed + expected impact}"},
|
|
96
|
+
{"label": "Generate {missing_schema_type} schema for this page", "description": "I'll produce ready-to-use JSON-LD — copy it into your <head>"},
|
|
97
|
+
{"label": "Compare this page against a ranking competitor", "description": "Find a competitor ranking for {target_keyword} — I'll show you the gap"},
|
|
98
|
+
{"label": "Run full site audit to see site-wide patterns", "description": "Check if these issues affect other pages too — full health score for the whole domain"}
|
|
99
|
+
]
|
|
100
|
+
}]</parameter>
|
|
101
|
+
</invoke>
|
|
102
|
+
```
|
|
86
103
|
|
|
87
104
|
## Output
|
|
88
105
|
|
|
89
|
-
Per-dimension scores (0–100) with specific findings. Prioritized fix list. Overall page score.
|
|
106
|
+
Per-dimension scores (0–100) with specific findings. Prioritized fix list with exact changes. Overall page score. If target keyword was provided, keyword-specific recommendations.
|
|
90
107
|
|
|
91
108
|
## Fallbacks
|
|
92
109
|
|
|
93
|
-
**If
|
|
94
|
-
Present options as a numbered list
|
|
110
|
+
**If AskUserQuestion is unavailable:**
|
|
111
|
+
Present options as a numbered list. Example:
|
|
95
112
|
|
|
96
113
|
```
|
|
97
|
-
|
|
98
|
-
1.
|
|
99
|
-
2.
|
|
100
|
-
3.
|
|
114
|
+
What would you like to do next?
|
|
115
|
+
1. Fix the top issue now
|
|
116
|
+
2. Generate schema markup for this page
|
|
117
|
+
3. Run a full site audit
|
|
101
118
|
```
|
package/package.json
CHANGED
|
@@ -1,10 +1,9 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Codex config.toml writer.
|
|
3
3
|
*
|
|
4
|
-
* Codex hooks
|
|
5
|
-
* project-local
|
|
6
|
-
*
|
|
7
|
-
* `codex_hooks = true` feature flag and the inline lifecycle hook tables.
|
|
4
|
+
* Codex hooks require the `[features].hooks = true` flag in config.toml.
|
|
5
|
+
* AgileFlow uses the project-local `config.toml` path because we need both
|
|
6
|
+
* the feature flag and the inline lifecycle hook tables.
|
|
8
7
|
*
|
|
9
8
|
* The writer is non-destructive:
|
|
10
9
|
* - it preserves unrelated top-level Codex config
|
|
@@ -136,7 +135,7 @@ function mergeManagedHooks(existing) {
|
|
|
136
135
|
: {};
|
|
137
136
|
next.features = {
|
|
138
137
|
...existingFeatures,
|
|
139
|
-
|
|
138
|
+
hooks: true,
|
|
140
139
|
collaboration_modes: true,
|
|
141
140
|
};
|
|
142
141
|
next.approval_policy = DEFAULT_APPROVAL_POLICY;
|
|
@@ -184,7 +183,7 @@ function unmanageHooks(existing) {
|
|
|
184
183
|
!Array.isArray(next.features)
|
|
185
184
|
) {
|
|
186
185
|
const features = { ...next.features };
|
|
187
|
-
delete features.
|
|
186
|
+
delete features.hooks;
|
|
188
187
|
delete features.collaboration_modes;
|
|
189
188
|
if (Object.keys(features).length) next.features = features;
|
|
190
189
|
else delete next.features;
|
|
@@ -55,7 +55,10 @@ const {
|
|
|
55
55
|
unmirrorClaudeCodeAgents,
|
|
56
56
|
} = require("../ide/claude-code-content.js");
|
|
57
57
|
const { loadSkill } = require("../skills/validator.js");
|
|
58
|
-
const {
|
|
58
|
+
const {
|
|
59
|
+
resolveSkillsDir,
|
|
60
|
+
resolveLearnFile,
|
|
61
|
+
} = require("../skills/learnings.js");
|
|
59
62
|
|
|
60
63
|
/**
|
|
61
64
|
* @typedef {import('../plugins/registry.js').PluginManifest} PluginManifest
|
|
@@ -224,6 +227,7 @@ async function removeDisabledPlugins(
|
|
|
224
227
|
async function scaffoldSkillLearnings(ordered, projectRoot) {
|
|
225
228
|
/** @type {string[]} */
|
|
226
229
|
const created = [];
|
|
230
|
+
const skillsDir = resolveSkillsDir(projectRoot);
|
|
227
231
|
for (const plugin of ordered) {
|
|
228
232
|
const skills = (plugin.provides && plugin.provides.skills) || [];
|
|
229
233
|
for (const s of skills) {
|
|
@@ -238,12 +242,20 @@ async function scaffoldSkillLearnings(ordered, projectRoot) {
|
|
|
238
242
|
}
|
|
239
243
|
const fm = manifest.frontmatter;
|
|
240
244
|
if (!fm || !fm.learns || fm.learns.enabled !== true) continue;
|
|
241
|
-
const
|
|
245
|
+
const learnFile =
|
|
242
246
|
typeof fm.learns.file === "string" && fm.learns.file
|
|
243
247
|
? fm.learns.file
|
|
244
|
-
:
|
|
245
|
-
const
|
|
246
|
-
|
|
248
|
+
: undefined;
|
|
249
|
+
const p = resolveLearnFile(skillsDir, manifest.skillId, learnFile);
|
|
250
|
+
await fs.promises.mkdir(path.dirname(p), { recursive: true });
|
|
251
|
+
try {
|
|
252
|
+
await fs.promises.access(p);
|
|
253
|
+
} catch (err) {
|
|
254
|
+
if (err.code !== "ENOENT") throw err;
|
|
255
|
+
const header = `# AgileFlow skill learnings — ${manifest.skillId}\n# Append-only signals; oldest trimmed when count exceeds maxEntries.\nentries: []\n`;
|
|
256
|
+
await fs.promises.writeFile(p, header, "utf8");
|
|
257
|
+
created.push(manifest.skillId);
|
|
258
|
+
}
|
|
247
259
|
}
|
|
248
260
|
}
|
|
249
261
|
return created;
|