@maccesar/titools 2.0.7 → 2.2.1

package/AGENTS-TEMPLATE.md

@@ -1,174 +0,0 @@
-# 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-START -->
-<!-- Version: v2.0.7 -->
-<!--
-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
-```

package/lib/commands/install.js

@@ -1,188 +0,0 @@
-/**
- * Install command
- * Installs skills and agents to AI coding assistant directories
- */
-
-import inquirer from 'inquirer';
-import chalk from 'chalk';
-import ora from 'ora';
-import {
-  SKILLS,
-  AGENTS,
-  REPO_URL,
-} from '../config.js';
-import {
-  detectPlatforms,
-  detectOS,
-} from '../platform.js';
-import {
-  installSkills,
-  installAgents,
-  installAgentsTemplate,
-  getLocalRepoDir,
-} from '../installer.js';
-import { downloadRepoArchive } from '../downloader.js';
-import { createSkillSymlinks } from '../symlink.js';
-import { formatList } from '../utils.js';
-import { mkdtemp } from 'fs/promises';
-import { join } from 'path';
-import { tmpdir } from 'os';
-
-/**
- * Install command handler
- * @param {Object} options - Command options
- */
-export async function installCommand(options) {
-  console.log('');
-  console.log(chalk.bold.blue('Titanium SDK Skills Installer'));
-  console.log('');
-
-  // Detect installed platforms
-  const detectedPlatforms = detectPlatforms();
-
-  if (detectedPlatforms.length === 0 && !options.path) {
-    console.log(chalk.yellow('No AI coding assistants detected.'));
-    console.log('Install one of: Claude Code, Gemini CLI, or Codex CLI');
-    console.log('Or use: titools install --path /custom/path');
-    process.exit(1);
-  }
-
-  // Show detected platforms
-  for (const platform of detectedPlatforms) {
-    console.log(chalk.green('✓'), `${platform.displayName} detected`);
-  }
-  console.log('');
-
-  // Select platforms to install
-  let selectedPlatforms = [];
-
-  if (options.path) {
-    // Custom path mode - skip platform selection
-    selectedPlatforms = [];
-  } else if (options.all) {
-    // Install to all detected platforms
-    selectedPlatforms = detectedPlatforms;
-  } else {
-    // Interactive selection
-    const answers = await inquirer.prompt([
-      {
-        type: 'list',
-        name: 'platform',
-        message: 'Select platform to install:',
-        choices: [
-          { name: 'All detected platforms', value: 'all' },
-          ...detectedPlatforms.map((p) => ({
-            name: `${p.displayName} only`,
-            value: p.name,
-          })),
-          { name: 'Cancel', value: 'cancel' },
-        ],
-      },
-    ]);
-
-    if (answers.platform === 'cancel') {
-      console.log('Cancelled.');
-      process.exit(0);
-    }
-
-    if (answers.platform === 'all') {
-      selectedPlatforms = detectedPlatforms;
-    } else {
-      selectedPlatforms = detectedPlatforms.filter(
-        (p) => p.name === answers.platform
-      );
-    }
-  }
-
-  if (selectedPlatforms.length === 0 && !options.path) {
-    console.log('No platforms selected.');
-    process.exit(0);
-  }
-
-  // Get repository directory (local or download)
-  const spinner = ora();
-  let repoDir = getLocalRepoDir();
-
-  if (!repoDir) {
-    // Download from GitHub
-    spinner.start('Downloading from GitHub...');
-    try {
-      const tempDir = tmpdir();
-      repoDir = await mkdtemp(join(tempDir, 'titanium-skills-'));
-      await downloadRepoArchive(repoDir);
-      spinner.succeed('Downloaded from GitHub');
-    } catch (error) {
-      spinner.fail('Failed to download');
-      console.error(chalk.red(error.message));
-      process.exit(1);
-    }
-  } else {
-    console.log(chalk.green('Using local repository'));
-  }
-
-  try {
-    // Install skills
-    spinner.start('Installing skills...');
-    const skillsResult = await installSkills(repoDir);
-    spinner.succeed(
-      `Skills: ${formatList(skillsResult.installed)}`
-    );
-
-    // Install agents
-    spinner.start('Installing agents...');
-    const agentsResult = await installAgents(repoDir);
-    if (agentsResult.installed.length > 0) {
-      spinner.succeed(
-        `Agents: ${formatList(agentsResult.installed)}`
-      );
-    } else {
-      spinner.info('No agents to install (Claude Code not detected)');
-    }
-
-    // Install AGENTS-TEMPLATE.md
-    spinner.start('Installing AGENTS-TEMPLATE.md...');
-    const templateInstalled = await installAgentsTemplate(repoDir);
-    if (templateInstalled) {
-      spinner.succeed('AGENTS-TEMPLATE.md installed');
-    } else {
-      spinner.warn('AGENTS-TEMPLATE.md not found');
-    }
-
-    // Create symlinks for selected platforms
-    for (const platform of selectedPlatforms) {
-      spinner.start(`Linking ${platform.displayName}...`);
-      const symlinkResult = await createSkillSymlinks(
-        platform.skillsDir,
-        SKILLS
-      );
-      if (symlinkResult.linked.length === SKILLS.length) {
-        spinner.succeed(`${platform.displayName} linked`);
-      } else {
-        spinner.warn(
-          `${platform.displayName}: ${symlinkResult.linked.length}/${SKILLS.length} linked`
-        );
-      }
-    }
-
-    // Summary
-    console.log('');
-    console.log(chalk.green('✓ Installation complete!'));
-    console.log('');
-    console.log(chalk.bold('▸'), 'Add AGENTS.md to your project:', chalk.cyan('titools agents'));
-    console.log(chalk.bold('▸'), 'Improves AI:', chalk.red('53%'), '→', chalk.green('100%'));
-    console.log('');
-
-    if (detectOS() === 'windows') {
-      console.log(chalk.yellow('▸'), 'Windows: Ensure ~/bin is in your PATH');
-      console.log('');
-    }
-
-  } finally {
-    // Clean up temp directory if we downloaded
-    if (repoDir !== getLocalRepoDir() && repoDir.startsWith(tmpdir())) {
-      await import('fs-extra').then(({ remove }) => remove(repoDir));
-    }
-  }
-}
-
-export default installCommand;

package/skills/alloy-expert/references/anti-patterns.md

@@ -1,133 +0,0 @@
-# Titanium Alloy + PurgeTSS Anti-Patterns
-
-## 1. Manual Styling (Legacy & Overwrite Risk)
-**Symptom:** Editing `app.tss` manually or using inline attributes like `backgroundColor="#fff"`.
-**Problem:** PurgeTSS will overwrite manual changes in `app.tss`. Inline attributes make theme changes impossible.
-**Solution:** Use **PurgeTSS classes** in XML.
-
-## 2. Fat Controllers
-**Symptom:** Controllers with 100+ lines handling logic, API, and UI.
-**Solution:** Delegate business logic to `lib/services/` and API calls to `lib/api/`.
-
-## 3. Memory Leaks (Missing Cleanup)
-**Symptom:** Adding `Ti.App` or `Alloy.Collections` listeners without a `cleanup()` function.
-**Solution:** Always implement `$.cleanup = cleanup` and remove listeners there.
-
-## 4. Direct Native Module Calls
-**Symptom:** Calling `require('ti.module')` directly in a controller.
-**Solution:** Wrap it in a service in `lib/services/` (e.g., `audioService.js`).
-
-## 5. Direct Controller Navigation
-**Symptom:** `Alloy.createController('name').getView().open()`.
-**Solution:** Use a Navigation Service to centralize `open/close` and trigger the `cleanup()` function automatically.
-
-## 6. Complex Matrix Animations
-**Symptom:** Manual use of `Ti.UI.create2DMatrix()`.
-**Solution:** Use the **PurgeTSS Animation Module** with state modifiers (`class="close:opacity-0 open:opacity-100"`).
-
-## 7. Hardcoded Strings & Missing a11y
-**Symptom:** `text="Login"` instead of `text="L('login')"`, or missing `accessibilityLabel`.
-**Solution:** Always use i18n and accessibility properties.
-
-## 8. Logic in TSS
-**Symptom:** Using conditionals or calculations inside TSS.
-**Solution:** Keep styling declarative through PurgeTSS classes.
-
----
-
-## PurgeTSS-Specific Anti-Patterns
-
-## 9. Flexbox Classes (Don't Exist)
-**Symptom:** Using `flex-row`, `flex-col`, `justify-between`, `justify-center`, `items-center`.
-**Problem:** Titanium does NOT support CSS Flexbox. These classes don't exist in PurgeTSS.
-**Solution:** Use Titanium layout modes:
-```xml
-<!-- WRONG -->
-<View class="flex-row justify-between">
-
-<!-- CORRECT -->
-<View class="horizontal">
-```
-
-## 10. Padding on Container Views
-**Symptom:** Using `p-4`, `px-2`, `py-3` on View, Window, ScrollView, or TableView.
-**Problem:** Base container elements don't support padding in Titanium.
-**Solution:** Use margins on children instead:
-```xml
-<!-- WRONG -->
-<View class="p-4">
-  <Label text="Hello" />
-</View>
-
-<!-- CORRECT -->
-<View>
-  <Label class="m-4" text="Hello" />
-</View>
-```
-
-## 11. Confusing `w-full` with `w-screen`
-**Symptom:** Using `w-full` when `w-screen` is needed.
-**Difference:** `w-full` sets `width: '100%'` (100% of parent), while `w-screen` sets `width: Ti.UI.FILL` (fills available space).
-**Solution:** Use `w-screen` for full-width elements that should fill space. `w-full` is useful when you need percentage-based sizing.
-
-## 12. Using `rounded-full` Without Size
-**Symptom:** Using `rounded-full` expecting a circle.
-**Problem:** `rounded-full` (without number) doesn't exist. You need `rounded-full-XX` where XX × 4 = element size.
-**Note:** `rounded-full-XX` already includes width and height. Don't add `w-XX h-XX` with it.
-**Solution:** For a 48×48 circle, use `rounded-full-12` (includes size). For percentage-based, use `w-12 h-12 rounded-full`.
-
-## 13. Adding `composite` Class Explicitly
-**Symptom:** Adding `class="composite"` to Views.
-**Problem:** Composite (absolute positioning) is the DEFAULT layout. Adding it is redundant.
-**Solution:** Omit layout class for composite, only use `horizontal` or `vertical` when needed.
-
-## 14. Square Brackets for Arbitrary Values
-**Symptom:** Using `w-[100px]` or `bg-[#ff0000]` with square brackets.
-**Problem:** PurgeTSS uses parentheses, not square brackets.
-**Solution:** Use parentheses: `w-(100px)`, `bg-(#ff0000)`.
-
-## 15. Creating Manual .tss Files Per Controller
-**Symptom:** Creating `app/styles/login.tss`, `app/styles/profile.tss`, etc.
-**Problem:** Defeats the purpose of PurgeTSS which auto-generates a single optimized `app.tss`.
-**Solution:** Use ONLY utility classes in XML. Delete all manual `.tss` files except `_app.tss`.
-
-## 16. Using `lib/` Prefix in Require Statements
-**Symptom:** `const service = require('lib/services/picsum')`
-**Problem:** Alloy flattens the `lib/` folder during build. Files in `app/lib/services/` become `Resources/iphone/services/`.
-**Solution:** Omit the `lib/` prefix: `const service = require('services/picsum')`
-
-## 17. Wrong Window ID in Controller
-**Symptom:** Using `$.index.open()` when the Window has `id="mainWindow"`.
-**Problem:** Alloy generates `$` references from XML IDs. If Window is `id="mainWindow"`, `$.index` doesn't exist.
-**Solution:** Match the ID: `$.mainWindow.open()`
-
-## 18. Using `Ti.UI.createNotification`
-**Symptom:** `Ti.UI.createNotification({ message: 'Hi' }).show()`
-**Problem:** This API doesn't exist in Titanium. Causes "invalid method" error.
-**Solution:** Use `Ti.UI.createAlertDialog` for simple messages, or create custom toast views.
-
-## 19. Using Nonexistent iOS Share APIs
-**Symptom:** `Ti.UI.iOS.createActivityPopover` or `alloy/social` with wrong methods.
-**Problem:** These APIs either don't exist or have changed. Causes runtime errors.
-**Solution:**
-- iOS: Use `Ti.UI.iOS.createDocumentViewer` for files, or simple `Ti.UI.createOptionDialog` + `Ti.UI.Clipboard` for links
-- Android: Use `Ti.Android.createIntent` with ACTION_SEND
-
----
-
-## Quick Reference Table
-
-| Anti-Pattern         | Why It Fails             | Correct Approach        |
-| -------------------- | ------------------------ | ----------------------- |
-| `flex-row`           | Flexbox not supported    | `horizontal`            |
-| `flex-col`           | Flexbox not supported    | `vertical`              |
-| `justify-*`          | Flexbox not supported    | Use margins/positioning |
-| `p-4` on View        | No padding on containers | `m-4` on children       |
-| `w-full`             | Doesn't exist            | `w-screen`              |
-| `rounded-full`       | Needs size suffix        | `rounded-full-12`       |
-| `composite` class    | Already default          | Omit it                 |
-| `w-[100px]`          | Wrong syntax             | `w-(100px)`             |
-| Manual `.tss`        | Overwritten by PurgeTSS  | Use utility classes     |
-| `lib/` prefix        | lib/ is flattened        | Use path without lib/   |
-| `$.index.open()`     | Wrong ID reference       | Use actual Window ID    |
-| `createNotification` | API doesn't exist        | `createAlertDialog`     |