@maccesar/titools 2.2.0 → 2.2.1

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 (4) hide show
  1. package/AGENTS-VERCEL-RESEARCH.md +62 -62
  2. package/README.md +337 -400
  3. package/agents/ti-pro.md +5 -4
  4. 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,9 +36,9 @@ 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
@@ -47,56 +47,56 @@ The index uses a compressed format that maps skills to their reference documenta
47
47
  |ti-ui/references:{listviews-and-performance.md,layouts-and-positioning.md,...}
48
48
  ```
49
49
 
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`
50
+ How the assistant should use it:
53
51
  - Need Backbone.Models patterns? Read `~/.agents/skills/alloy-guides/references/MODELS.md`
52
+ - Need the PurgeTSS grid system? Read `~/.agents/skills/purgetss/references/grid-layout.md`
53
+ - Need ListView performance tips? Read `~/.agents/skills/ti-ui/references/listviews-and-performance.md`
54
54
 
55
- ### Skill Overview
55
+ ### Skill overview
56
56
 
57
- | Skill | Purpose | Best For |
57
+ | Skill | Purpose | Best for |
58
58
  | ---------------- | ----------------------------- | --------------------------------------------- |
59
- | **ti-expert** | Architecture + Implementation | Starting point for most Alloy tasks |
59
+ | **alloy-guides** | Alloy MVC reference | Models, views, controllers, widgets |
60
+ | **alloy-howtos** | Alloy CLI and debugging | Project setup, CLI commands, errors |
60
61
  | **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 |
62
+ | **ti-expert** | Architecture + implementation | Starting point for most Alloy tasks |
63
63
  | **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 |
64
+ | **ti-howtos** | Native feature integration | Location, push, media, platform-specific APIs |
65
+ | **ti-ui** | UI/UX patterns | Layouts, ListViews, gestures, platform UI |
66
66
 
67
- ### For Complex Workflows
67
+ ### For complex workflows
68
68
 
69
69
  The **ti-pro** agent (installed in `~/.claude/agents/`) handles:
70
70
  - Codebase architecture analysis
71
71
  - Multi-feature research across Titanium APIs
72
72
  - Cross-referencing framework patterns
73
- - Platform-specific differences investigation
73
+ - Platform-specific differences
74
74
 
75
- It preloads all 7 titanium-* skills for comprehensive analysis.
75
+ It preloads all 7 titanium-* skills for broader coverage.
76
76
 
77
- ## How to Use
77
+ ## How to use
78
78
 
79
- ### For Titanium Projects
79
+ ### For Titanium projects
80
80
 
81
- Run the `titools sync` command in your Titanium project root:
81
+ Run `titools sync` from your project root:
82
82
 
83
83
  ```bash
84
84
  cd /path/to/your/titanium/project
85
85
  titools sync
86
86
  ```
87
87
 
88
- This creates/updates:
89
- - `CLAUDE.md` (for Claude Code)
90
- - `GEMINI.md` (for Gemini CLI)
91
- - `AGENTS.md` (for Cursor/Copilot)
88
+ This creates or updates:
89
+ - `AGENTS.md` (Codex CLI and others)
90
+ - `CLAUDE.md` (Claude Code)
91
+ - `GEMINI.md` (Gemini CLI)
92
92
 
93
- ### What Gets Generated
93
+ ### What gets generated
94
94
 
95
- The generated file contains:
95
+ The generated file includes:
96
96
 
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
97
+ 1. **Version marker**: tracks docs version
98
+ 2. **Block boundaries**: support automatic updates
99
+ 3. **Compressed index**: maps skills to reference files
100
100
 
101
101
  Example output:
102
102
 
@@ -124,46 +124,46 @@ This knowledge index is based on the latest Titanium SDK documentation.
124
124
  <!-- END-TITANIUM-KNOWLEDGE -->
125
125
  ```
126
126
 
127
- ### Updating the Index
127
+ ### Updating the index
128
128
 
129
- When you update titools, simply re-run the command:
129
+ When you update titools, re-run:
130
130
 
131
131
  ```bash
132
132
  titools update # Update skills and docs
133
- titools sync # Regenerate index in your project
133
+ titools sync # Regenerate index in your project
134
134
  ```
135
135
 
136
- The old block is automatically replaced with the new version.
136
+ The block is replaced automatically.
137
137
 
138
- ## Version Notice
138
+ ## Version notice
139
139
 
140
- The knowledge index is based on the **latest Titanium SDK documentation**.
140
+ The index is based on the **latest Titanium SDK docs**.
141
141
 
142
- **To check your project's version:**
142
+ To check your project's version:
143
143
  ```bash
144
144
  grep -A 1 "<sdk-version>" tiapp.xml
145
145
  ```
146
146
 
147
- **If there's a version mismatch:**
147
+ If there's a mismatch:
148
148
  - 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
149
+ - Older deprecated patterns may still be valid
150
+ - Verify against your version's official docs: https://titaniumsdk.com/guide
151
151
 
152
- ## Key Takeaways from Vercel's Research
152
+ ## Key takeaways from Vercel's research
153
153
 
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
154
+ 1. **Passive context beats active retrieval**: always-present info performs better than info that must be loaded
155
+ 2. **No activation needed**: the model does not need to decide when to use a skill
156
+ 3. **Consistent behavior**: same inputs every time, regardless of prompt wording
157
+ 4. **100% pass rate**: AGENTS.md approach achieved perfect performance in their evals
158
158
 
159
159
  ## References
160
160
 
161
- - [Vercel's Blog: agents.md Outperforms Skills in Our Agent Evals](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals)
161
+ - [Vercel's blog: AGENTS.md outperforms skills in our agent evals](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals)
162
162
  - [Repository: macCesar/titools](https://github.com/macCesar/titools)
163
163
 
164
164
  ## Maintenance
165
165
 
166
- This approach is maintained in the [titools](https://github.com/macCesar/titools) project.
166
+ This approach is maintained in [titools](https://github.com/macCesar/titools).
167
167
 
168
168
  To update your installation:
169
169
  ```bash