@maccesar/titools 2.0.7 → 2.2.1

package/AGENTS-VERCEL-RESEARCH.md

@@ -0,0 +1,172 @@
+# Why AGENTS.md? (Based on Vercel's research)
+
+This explains why we use AGENTS.md or CLAUDE.md with a compressed docs index instead of relying only on skills.
+
+## The problem: skills alone underperform
+
+Vercel reports that skills-only setups hit a **53-79% pass rate** on coding tasks.
+
+### Why skills underperform
+
+| Issue               | Description                                           |
+| ------------------- | ----------------------------------------------------- |
+| **Decision point**  | The model has to decide when to invoke a skill        |
+| **Async loading**   | Skills load on-demand, so they are not always present |
+| **Ordering issues** | "Explore first" vs "read docs first" tradeoff         |
+| **Fragile prompts** | Results depend on exact prompt wording                |
+
+## The fix: AGENTS.md with a compressed index
+
+Vercel reports that AGENTS.md plus a compressed documentation index hit a **100% pass rate** in their evals.
+
+### Why it works
+
+1. **No decision point**: the info is already there
+2. **Consistent availability**: present every turn, not async
+3. **No ordering issues**: no docs vs project exploration dilemma
+4. **Passive context**: not dependent on the prompt
+
+### Performance comparison
+
+| Approach            | Pass rate |
+| ------------------- | --------- |
+| No documentation    | 53%       |
+| Skills only         | 53-79%    |
+| **AGENTS.md index** | **100%**  |
+
+## Implementation for Titanium SDK
+
+### Compressed index format
+
+The index maps skills to their reference docs:
+
+```
+[Titanium SDK Docs Index]|root: ~/.agents/skills
+|ti-expert/references:{alloy-structure.md,anti-patterns.md,...}
+|purgetss/references:{animation-system.md,apply-directive.md,...}
+|ti-ui/references:{listviews-and-performance.md,layouts-and-positioning.md,...}
+```
+
+How the assistant should use it:
+- Need Backbone.Models patterns? Read `~/.agents/skills/alloy-guides/references/MODELS.md`
+- Need the PurgeTSS grid system? Read `~/.agents/skills/purgetss/references/grid-layout.md`
+- Need ListView performance tips? Read `~/.agents/skills/ti-ui/references/listviews-and-performance.md`
+
+### Skill overview
+
+| Skill            | Purpose                       | Best for                                      |
+| ---------------- | ----------------------------- | --------------------------------------------- |
+| **alloy-guides** | Alloy MVC reference           | Models, views, controllers, widgets           |
+| **alloy-howtos** | Alloy CLI and debugging       | Project setup, CLI commands, errors           |
+| **purgetss**     | Utility-first styling         | UI styling, animations, grid layouts          |
+| **ti-expert**    | Architecture + implementation | Starting point for most Alloy tasks           |
+| **ti-guides**    | SDK fundamentals              | Hyperloop, distribution, tiapp.xml, CLI       |
+| **ti-howtos**    | Native feature integration    | Location, push, media, platform-specific APIs |
+| **ti-ui**        | UI/UX patterns                | Layouts, ListViews, gestures, platform UI     |
+
+### For complex workflows
+
+The **ti-pro** agent (installed in `~/.claude/agents/`) handles:
+- Codebase architecture analysis
+- Multi-feature research across Titanium APIs
+- Cross-referencing framework patterns
+- Platform-specific differences
+
+It preloads all 7 titanium-* skills for broader coverage.
+
+## How to use
+
+### For Titanium projects
+
+Run `titools sync` from your project root:
+
+```bash
+cd /path/to/your/titanium/project
+titools sync
+```
+
+This creates or updates:
+- `AGENTS.md` (Codex CLI and others)
+- `CLAUDE.md` (Claude Code)
+- `GEMINI.md` (Gemini CLI)
+
+### What gets generated
+
+The generated file includes:
+
+1. **Version marker**: tracks docs version
+2. **Block boundaries**: support automatic updates
+3. **Compressed index**: maps skills to reference files
+
+Example output:
+
+```html
+<!-- TITANIUM-KNOWLEDGE-START -->
+<!-- Version: vX.X.X -->
+## Titanium SDK Knowledge Index
+
+Generated by `titools` based on Vercel's research on AGENTS.md effectiveness.
+
+**IMPORTANT**: Prefer retrieval-led reasoning over pre-training-led reasoning when working with Titanium SDK.
+Always consult the documentation files below rather than relying on training data, which may be outdated.
+
+This knowledge index is based on the latest Titanium SDK documentation.
+
+### Compressed Documentation Index
+
+```
+[Titanium SDK Docs Index]|root: ~/.agents/skills
+|ti-expert/references:{alloy-structure.md,anti-patterns.md,code-conventions.md,contracts.md,controller-patterns.md,error-handling.md,examples.md,...}
+|alloy-guides/references:{CLI_TASKS.md,CONCEPTS.md,CONTROLLERS.md,MODELS.md,PURGETSS.md,VIEWS_DYNAMIC.md,VIEWS_STYLES.md,VIEWS_WITHOUT_CONTROLLERS.md,...}
+...
+```
+
+<!-- END-TITANIUM-KNOWLEDGE -->
+```
+
+### Updating the index
+
+When you update titools, re-run:
+
+```bash
+titools update      # Update skills and docs
+titools sync        # Regenerate index in your project
+```
+
+The block is replaced automatically.
+
+## Version notice
+
+The index is based on the **latest Titanium SDK docs**.
+
+To check your project's version:
+```bash
+grep -A 1 "<sdk-version>" tiapp.xml
+```
+
+If there's a mismatch:
+- Newer APIs may not exist in your version
+- Older deprecated patterns may still be valid
+- Verify against your version's official docs: https://titaniumsdk.com/guide
+
+## Key takeaways from Vercel's research
+
+1. **Passive context beats active retrieval**: always-present info performs better than info that must be loaded
+2. **No activation needed**: the model does not need to decide when to use a skill
+3. **Consistent behavior**: same inputs every time, regardless of prompt wording
+4. **100% pass rate**: AGENTS.md approach achieved perfect performance in their evals
+
+## References
+
+- [Vercel's blog: AGENTS.md outperforms skills in our agent evals](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals)
+- [Repository: macCesar/titools](https://github.com/macCesar/titools)
+
+## Maintenance
+
+This approach is maintained in [titools](https://github.com/macCesar/titools).
+
+To update your installation:
+```bash
+npm update -g @maccesar/titools
+titools update
+```