@maccesar/titools 2.0.0

package/AGENTS-TEMPLATE.md

@@ -0,0 +1,173 @@
+# Why AGENTS.md? (Based on Vercel's Research)
+
+This document explains why we use AGENTS.md/CLAUDE.md with compressed documentation indexes instead of relying solely on skills for AI coding assistants.
+
+## The Problem: Skills Alone Underperform
+
+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.
+
+### Why Skills Underperform
+
+| Issue               | Description                                           |
+| ------------------- | ----------------------------------------------------- |
+| **Decision point**  | AI must decide WHEN to invoke a skill (often doesn't) |
+| **Async loading**   | Skills loaded on-demand, not always available         |
+| **Ordering issues** | "Explore first vs read docs first" dilemma            |
+| **Fragile prompts** | Performance depends on exact prompt wording           |
+
+## The Solution: AGENTS.md with Compressed Index
+
+Vercel found that using AGENTS.md with a compressed documentation index achieves **100% pass rate**.
+
+### Why It Works
+
+1. **No decision point** - Information is always present, no need to invoke skills
+2. **Consistent availability** - Available in every turn, not async-loaded
+3. **No ordering issues** - No "read docs first vs explore project first" dilemma
+4. **Passive context** - Already in context, doesn't depend on prompt wording
+
+### Performance Comparison
+
+| Approach            | Pass Rate |
+| ------------------- | --------- |
+| No documentation    | 53%       |
+| Skills only         | 53-79%    |
+| **AGENTS.md index** | **100%**  |
+
+## Implementation for Titanium SDK
+
+### The Compressed Index Format
+
+The index uses a compressed format that maps skills to their reference documentation:
+
+```
+[Titanium SDK Docs Index]|root: ~/.agents/skills
+|alloy-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 AI uses it:**
+- Need ListView performance tips? Read `~/.agents/skills/ti-ui/references/listviews-and-performance.md`
+- Need PurgeTSS grid system? Read `~/.agents/skills/purgetss/references/grid-layout.md`
+- Need Backbone.Models patterns? Read `~/.agents/skills/alloy-guides/references/MODELS.md`
+
+### Skill Overview
+
+| Skill            | Purpose                       | Best For                                      |
+| ---------------- | ----------------------------- | --------------------------------------------- |
+| **alloy-expert** | Architecture + Implementation | Starting point for most Alloy tasks           |
+| **purgetss**     | Utility-first styling         | UI styling, animations, grid layouts          |
+| **ti-ui**        | UI/UX patterns                | Layouts, ListViews, gestures, platform UI     |
+| **ti-howtos**    | Native feature integration    | Location, Push, Media, platform-specific APIs |
+| **ti-guides**    | SDK fundamentals              | Hyperloop, distribution, tiapp.xml, CLI       |
+| **alloy-guides** | Alloy MVC reference           | Models, Views, Controllers, Widgets           |
+| **alloy-howtos** | Alloy CLI & debugging         | Project setup, CLI commands, errors           |
+
+### For Complex Workflows
+
+The **ti-researcher** agent (installed in `~/.claude/agents/`) handles:
+- Codebase architecture analysis
+- Multi-feature research across Titanium APIs
+- Cross-referencing framework patterns
+- Platform-specific differences investigation
+
+It preloads all 7 titanium-* skills for comprehensive analysis.
+
+## How to Use
+
+### For Titanium Projects
+
+Run the `titools agents` command in your Titanium project root:
+
+```bash
+cd /path/to/your/titanium/project
+titools agents
+```
+
+This creates/updates:
+- `CLAUDE.md` (for Claude Code)
+- `GEMINI.md` (for Gemini CLI)
+- `AGENTS.md` (for Cursor/Copilot)
+
+### What Gets Generated
+
+The generated file contains:
+
+1. **Version marker** - Tracks which version of the docs
+2. **Compressed index** - Maps all skills to their reference files
+3. **Block boundaries** - For automatic updates
+
+Example output:
+
+```html
+<!-- TITANIUM-KNOWLEDGE-v2.0.0 -->
+<!--
+Titanium SDK Knowledge Index
+Generated by titools -->
+Based on Vercel's research: https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals
+
+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
+|IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning when working with Titanium SDK...
+|alloy-expert/references:{alloy-structure.md,anti-patterns.md,code-conventions.md,...}
+...
+```
+
+<!-- END-TITANIUM-KNOWLEDGE -->
+```
+
+### Updating the Index
+
+When you update titools, simply re-run the command:
+
+```bash
+titools update      # Update skills and docs
+titools agents      # Regenerate index in your project
+```
+
+The old block is automatically replaced with the new version.
+
+## Version Notice
+
+The knowledge index is based on the **latest Titanium SDK documentation**.
+
+**To check your project's version:**
+```bash
+grep -A 1 "<sdk-version>" tiapp.xml
+```
+
+**If there's a version mismatch:**
+- Newer APIs may not exist in your version
+- Older deprecated patterns may still be valid for you
+- Always verify against your version's official docs: https://titaniumsdk.com/guide
+
+## Key Takeaways from Vercel's Research
+
+1. **Passive context > Active retrieval** - Information that's always present outperforms information that must be actively loaded
+2. **No activation needed** - The AI doesn't need to decide when to use a skill
+3. **Consistent behavior** - Same information every time, regardless of prompt wording
+4. **100% pass rate** - AGENTS.md approach achieves perfect performance on evaluated tasks
+
+## 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 the [titools](https://github.com/macCesar/titools) project.
+
+To update your installation:
+```bash
+npm update -g @maccesar/titools
+titools update
+```