Skip to content

AGENTS.md

Latest commit

 

History

History
52 lines (37 loc) · 3.75 KB

AGENTS.md

File metadata and controls

52 lines (37 loc) · 3.75 KB

Trycycle

This repo is a skill for AI coding agents such as Claude Code and Codex CLI. Users install it by cloning into their skills directory.

If you are here to install and use trycycle

Follow the instructions in README.md. Use the version you install, and ignore the rest of this document.

If you are here to work on trycycle

Structure

  • SKILL.md + subskills/ — the skill itself (what users install and run)
  • maintenance/ — scripts for updating skills from upstream (not user-facing)
  • README.md — human-facing install and usage docs

Principles

  • Improve the system, not the symptom — Prefer clean architecture and correctness over quick patches. We are not in a hurry.
  • Think of everybody - Trycycle must work across agents, projects, and repo conventions, and should follow local constraints instead of imposing its own. For example, we must work with all of the following:
    • Coding agent (Claude Code and Codex CLI are best tested, but all agents are welcome)
    • Type of project (could be anything from a brownfield bug fix to a massive greenfield project)
    • Repo structure and policies
    • Host system (win/wsl/mac/linux)
  • It's a skill, not software - prefer succinct, meaningful prose and bullet points to code or complex orchestration paths. Prioritize meaningful, direct, short instructions that generalize well.
  • User instructions are top priority - specific user instructions always have priority - when working on Trycycle, and within Trycycle
  • Don't ask the user - Trycycle is, by default, fire-and-forget. We want a minimum of user interaction. Wherever possible, avoid asking the user unless the alternative could cause harm. Trust the agents.
  • Keep the orchestrator minimal - work is done in the subagents; the orchestrator must save its context window for user interactions.

Process

  • All work in a worktree - create it before changing files and offer to land on local main & clean it up when finished
  • Safe merges to main — Never merge directly on main. Merge main into the feature branch first, resolve conflicts there, then git merge --ff-only on main. This prevents broken state on the working branch.
  • Don't create tests for skill changes, only code changes. This specific rule supercedes broader policies.

Subskills

The skills in subskills/ are generated by maintenance/import-skills.sh from upstream superpowers (by Jesse Vincent). Edit the prompt template and skill-specific instructions in maintenance/, then re-run the import script. Do not hand-edit the generated skill files.

Versioning

Trycycle uses git tags for version tracking. check-update.py runs at the start of every Trycycle session (SKILL.md step 0) and compares the user's local tag against origin/main to prompt for updates.

To release a new version:

  1. Commit all changes to main.
  2. Ask the user what version number to use — never pick one yourself.
  3. Tag: git tag v<version>
  4. Push: git push origin main --tags
  5. Update any local Trycycle installs you control by running git pull in each installed clone so your manual checks use the pushed version, not a stale checkout. Check the common skill locations for all supported agents, including:
    • Unix / WSL home directories such as ~/.claude/skills/trycycle, ~/.codex/skills/trycycle, and ~/.kimi/skills/trycycle
    • Windows-side installs visible from WSL, such as /mnt/c/Users/<user>/.claude/skills/trycycle, /mnt/c/Users/<user>/.codex/skills/trycycle, and /mnt/c/Users/<user>/.kimi/skills/trycycle
    • Native PowerShell installs in C:\Users\<user>\.claude\skills\trycycle, C:\Users\<user>\.codex\skills\trycycle, C:\Users\<user>\.kimi\skills\trycycle, and equivalent locations for any other agent-specific skill directories you know about