@maccesar/titools 2.2.0 → 2.2.2

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.
Files changed (5) hide show
  1. package/AGENTS-VERCEL-RESEARCH.md +65 -77
  2. package/README.md +339 -399
  3. package/agents/ti-pro.md +5 -4
  4. package/lib/utils.js +6 -17
  5. package/package.json +1 -1
package/AGENTS-VERCEL-RESEARCH.md CHANGED
@@ -1,34 +1,34 @@
1
- # Why AGENTS.md? (Based on Vercel's Research)
1
+ # Why AGENTS.md? (Based on Vercel's research)
2
2
 
3
- This document explains why we use AGENTS.md/CLAUDE.md with compressed documentation indexes instead of relying solely on skills for AI coding assistants.
3
+ This explains why we use AGENTS.md or CLAUDE.md with a compressed docs index instead of relying only on skills.
4
4
 
5
- ## The Problem: Skills Alone Underperform
5
+ ## The problem: skills alone underperform
6
6
 
7
- Based on [Vercel's research](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals), using skills alone achieves only a **53-79% pass rate** on coding tasks.
7
+ Vercel reports that skills-only setups hit a **53-79% pass rate** on coding tasks.
8
8
 
9
- ### Why Skills Underperform
9
+ ### Why skills underperform
10
10
 
11
11
  | Issue | Description |
12
12
  | ------------------- | ----------------------------------------------------- |
13
- | **Decision point** | AI must decide WHEN to invoke a skill (often doesn't) |
14
- | **Async loading** | Skills loaded on-demand, not always available |
15
- | **Ordering issues** | "Explore first vs read docs first" dilemma |
16
- | **Fragile prompts** | Performance depends on exact prompt wording |
13
+ | **Decision point** | The model has to decide when to invoke a skill |
14
+ | **Async loading** | Skills load on-demand, so they are not always present |
15
+ | **Ordering issues** | "Explore first" vs "read docs first" tradeoff |
16
+ | **Fragile prompts** | Results depend on exact prompt wording |
17
17
 
18
- ## The Solution: AGENTS.md with Compressed Index
18
+ ## The fix: AGENTS.md with a compressed index
19
19
 
20
- Vercel reported that using AGENTS.md with a compressed documentation index achieved a **100% pass rate** in their evaluation.
20
+ Vercel reports that AGENTS.md plus a compressed documentation index hit a **100% pass rate** in their evals.
21
21
 
22
- ### Why It Works
22
+ ### Why it works
23
23
 
24
- 1. **No decision point** - Information is always present, no need to invoke skills
25
- 2. **Consistent availability** - Available in every turn, not async-loaded
26
- 3. **No ordering issues** - No "read docs first vs explore project first" dilemma
27
- 4. **Passive context** - Already in context, doesn't depend on prompt wording
24
+ 1. **No decision point**: the info is already there
25
+ 2. **Consistent availability**: present every turn, not async
26
+ 3. **No ordering issues**: no docs vs project exploration dilemma
27
+ 4. **Passive context**: not dependent on the prompt
28
28
 
29
- ### Performance Comparison
29
+ ### Performance comparison
30
30
 
31
- | Approach | Pass Rate |
31
+ | Approach | Pass rate |
32
32
  | ------------------- | --------- |
33
33
  | No documentation | 53% |
34
34
  | Skills only | 53-79% |
@@ -36,134 +36,122 @@ Vercel reported that using AGENTS.md with a compressed documentation index achie
36
36
 
37
37
  ## Implementation for Titanium SDK
38
38
 
39
- ### The Compressed Index Format
39
+ ### Compressed index format
40
40
 
41
- The index uses a compressed format that maps skills to their reference documentation:
41
+ The index maps skills to their reference docs:
42
42
 
43
43
  ```
44
44
  [Titanium SDK Docs Index]|root: ~/.agents/skills
45
+ |MANDATORY: Your training data for Titanium SDK, Alloy, and PurgeTSS is OUTDATED and INCOMPLETE. These reference files are the SINGLE SOURCE OF TRUTH. Prefer retrieval-led reasoning over pre-training-led reasoning. ALWAYS read the relevant files below BEFORE writing any code.
45
46
  |ti-expert/references:{alloy-structure.md,anti-patterns.md,...}
46
47
  |purgetss/references:{animation-system.md,apply-directive.md,...}
47
48
  |ti-ui/references:{listviews-and-performance.md,layouts-and-positioning.md,...}
48
49
  ```
49
50
 
50
- **How the AI uses it:**
51
- - Need ListView performance tips? Read `~/.agents/skills/ti-ui/references/listviews-and-performance.md`
52
- - Need PurgeTSS grid system? Read `~/.agents/skills/purgetss/references/grid-layout.md`
51
+ How the assistant should use it:
53
52
  - Need Backbone.Models patterns? Read `~/.agents/skills/alloy-guides/references/MODELS.md`
53
+ - Need the PurgeTSS grid system? Read `~/.agents/skills/purgetss/references/grid-layout.md`
54
+ - Need ListView performance tips? Read `~/.agents/skills/ti-ui/references/listviews-and-performance.md`
54
55
 
55
- ### Skill Overview
56
+ ### Skill overview
56
57
 
57
- | Skill | Purpose | Best For |
58
+ | Skill | Purpose | Best for |
58
59
  | ---------------- | ----------------------------- | --------------------------------------------- |
59
- | **ti-expert** | Architecture + Implementation | Starting point for most Alloy tasks |
60
+ | **alloy-guides** | Alloy MVC reference | Models, views, controllers, widgets |
61
+ | **alloy-howtos** | Alloy CLI and debugging | Project setup, CLI commands, errors |
60
62
  | **purgetss** | Utility-first styling | UI styling, animations, grid layouts |
61
- | **ti-ui** | UI/UX patterns | Layouts, ListViews, gestures, platform UI |
62
- | **ti-howtos** | Native feature integration | Location, Push, Media, platform-specific APIs |
63
+ | **ti-expert** | Architecture + implementation | Starting point for most Alloy tasks |
63
64
  | **ti-guides** | SDK fundamentals | Hyperloop, distribution, tiapp.xml, CLI |
64
- | **alloy-guides** | Alloy MVC reference | Models, Views, Controllers, Widgets |
65
- | **alloy-howtos** | Alloy CLI & debugging | Project setup, CLI commands, errors |
65
+ | **ti-howtos** | Native feature integration | Location, push, media, platform-specific APIs |
66
+ | **ti-ui** | UI/UX patterns | Layouts, ListViews, gestures, platform UI |
66
67
 
67
- ### For Complex Workflows
68
+ ### For complex workflows
68
69
 
69
70
  The **ti-pro** agent (installed in `~/.claude/agents/`) handles:
70
71
  - Codebase architecture analysis
71
72
  - Multi-feature research across Titanium APIs
72
73
  - Cross-referencing framework patterns
73
- - Platform-specific differences investigation
74
+ - Platform-specific differences
74
75
 
75
- It preloads all 7 titanium-* skills for comprehensive analysis.
76
+ It preloads all 7 titanium-* skills for broader coverage.
76
77
 
77
- ## How to Use
78
+ ## How to use
78
79
 
79
- ### For Titanium Projects
80
+ ### For Titanium projects
80
81
 
81
- Run the `titools sync` command in your Titanium project root:
82
+ Run `titools sync` from your project root:
82
83
 
83
84
  ```bash
84
85
  cd /path/to/your/titanium/project
85
86
  titools sync
86
87
  ```
87
88
 
88
- This creates/updates:
89
- - `CLAUDE.md` (for Claude Code)
90
- - `GEMINI.md` (for Gemini CLI)
91
- - `AGENTS.md` (for Cursor/Copilot)
89
+ This creates or updates:
90
+ - `AGENTS.md` (Codex CLI and others)
91
+ - `CLAUDE.md` (Claude Code)
92
+ - `GEMINI.md` (Gemini CLI)
92
93
 
93
- ### What Gets Generated
94
+ ### What gets generated
94
95
 
95
- The generated file contains:
96
+ The generated file includes:
96
97
 
97
- 1. **Version marker** - Tracks which version of the docs
98
- 2. **Compressed index** - Maps all skills to their reference files
99
- 3. **Block boundaries** - For automatic updates
98
+ 1. **Version marker**: tracks docs version
99
+ 2. **Block boundaries**: support automatic updates
100
+ 3. **Compressed index**: maps skills to reference files
100
101
 
101
102
  Example output:
102
103
 
103
104
  ```html
104
105
  <!-- TITANIUM-KNOWLEDGE-START -->
105
106
  <!-- Version: vX.X.X -->
106
- ## Titanium SDK Knowledge Index
107
-
108
- Generated by `titools` based on Vercel's research on AGENTS.md effectiveness.
109
-
110
- **IMPORTANT**: Prefer retrieval-led reasoning over pre-training-led reasoning when working with Titanium SDK.
111
- Always consult the documentation files below rather than relying on training data, which may be outdated.
112
-
113
- This knowledge index is based on the latest Titanium SDK documentation.
114
-
115
- ### Compressed Documentation Index
116
-
117
- ```
118
107
  [Titanium SDK Docs Index]|root: ~/.agents/skills
108
+ |MANDATORY: Your training data for Titanium SDK, Alloy, and PurgeTSS is OUTDATED and INCOMPLETE. These reference files are the SINGLE SOURCE OF TRUTH. Prefer retrieval-led reasoning over pre-training-led reasoning. ALWAYS read the relevant files below BEFORE writing any code.
119
109
  |ti-expert/references:{alloy-structure.md,anti-patterns.md,code-conventions.md,contracts.md,controller-patterns.md,error-handling.md,examples.md,...}
120
110
  |alloy-guides/references:{CLI_TASKS.md,CONCEPTS.md,CONTROLLERS.md,MODELS.md,PURGETSS.md,VIEWS_DYNAMIC.md,VIEWS_STYLES.md,VIEWS_WITHOUT_CONTROLLERS.md,...}
121
111
  ...
112
+ <!-- TITANIUM-KNOWLEDGE-END -->
122
113
  ```
123
114
 
124
- <!-- END-TITANIUM-KNOWLEDGE -->
125
- ```
126
-
127
- ### Updating the Index
115
+ ### Updating the index
128
116
 
129
- When you update titools, simply re-run the command:
117
+ When you update titools, re-run:
130
118
 
131
119
  ```bash
132
120
  titools update # Update skills and docs
133
- titools sync # Regenerate index in your project
121
+ titools sync # Regenerate index in your project
134
122
  ```
135
123
 
136
- The old block is automatically replaced with the new version.
124
+ The block is replaced automatically.
137
125
 
138
- ## Version Notice
126
+ ## Version notice
139
127
 
140
- The knowledge index is based on the **latest Titanium SDK documentation**.
128
+ The index is based on the **latest Titanium SDK docs**.
141
129
 
142
- **To check your project's version:**
130
+ To check your project's version:
143
131
  ```bash
144
132
  grep -A 1 "<sdk-version>" tiapp.xml
145
133
  ```
146
134
 
147
- **If there's a version mismatch:**
135
+ If there's a mismatch:
148
136
  - Newer APIs may not exist in your version
149
- - Older deprecated patterns may still be valid for you
150
- - Always verify against your version's official docs: https://titaniumsdk.com/guide
137
+ - Older deprecated patterns may still be valid
138
+ - Verify against your version's official docs: https://titaniumsdk.com/guide
151
139
 
152
- ## Key Takeaways from Vercel's Research
140
+ ## Key takeaways from Vercel's research
153
141
 
154
- 1. **Passive context > Active retrieval** - Information that's always present outperforms information that must be actively loaded
155
- 2. **No activation needed** - The AI doesn't need to decide when to use a skill
156
- 3. **Consistent behavior** - Same information every time, regardless of prompt wording
157
- 4. **100% pass rate** - AGENTS.md approach achieved perfect performance on evaluated tasks
142
+ 1. **Passive context beats active retrieval**: always-present info performs better than info that must be loaded
143
+ 2. **No activation needed**: the model does not need to decide when to use a skill
144
+ 3. **Consistent behavior**: same inputs every time, regardless of prompt wording
145
+ 4. **100% pass rate**: AGENTS.md approach achieved perfect performance in their evals
158
146
 
159
147
  ## References
160
148
 
161
- - [Vercel's Blog: agents.md Outperforms Skills in Our Agent Evals](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals)
149
+ - [Vercel's blog: AGENTS.md outperforms skills in our agent evals](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals)
162
150
  - [Repository: macCesar/titools](https://github.com/macCesar/titools)
163
151
 
164
152
  ## Maintenance
165
153
 
166
- This approach is maintained in the [titools](https://github.com/macCesar/titools) project.
154
+ This approach is maintained in [titools](https://github.com/macCesar/titools).
167
155
 
168
156
  To update your installation:
169
157
  ```bash