Generate modes

Generate modes

Goal

Create three project-specific, behavioral mode skills under ./​.{AGENT_NAME}/​skills/:

• {slug}-mode-planner
• {slug}-mode-debugger
• {slug}-mode-qa-tester

Each mode must:

1. Always state acceptance criteria and how to verify locally.
2. Never change or weaken existing tests without explicit approval.
3. When drafting skills, follow the Agent Skills spec (valid frontmatter; keep SKILL.md under ~500 lines; use progressive disclosure).

The modes must be written so they do not reference any specific benchmark, puzzle set, or domain-specific toy terms. They must read as general-purpose operating procedures.

For concrete “golden” examples of what the generated mode SKILL.md files should look like after adaptation, see references/​examples.md.

Quick start

1. Activate memories

   • Run $activating-memories.
   • Ensure baseline memory skills exist under ./​.{AGENT_NAME}/​skills/​memories/
   • If memories are missing or stale, update them before generating modes.

2. Choose a project slug

   • Prefer a slug stated in project_overview.
   • Otherwise derive from the repository folder name.
   • Slug rules: lowercase, digits, hyphens; no leading/​trailing hyphen; no consecutive hyphens.
   • Length rule (spec compliance): generated skill name must be ≤ 64 chars and match its directory name.
     • Longest suffix is -mode-qa-tester (15 chars), so {slug} must be ≤ 49 chars.

3. Read the bundled templates

   • Read:
     • assets/​planner-template.md
     • assets/​debugger-template.md
     • assets/​qa-tester-template.md

4. Generate three mode skills For each template:

   • Adapt it to the project by adding:
     • the {slug} mode name
     • links to relevant memories (do not paste memory contents)
     • project-specific verification commands (link to suggested_commands-skl for the canonical list)
   • Write the resulting skill to:
     • ./​.{AGENT_NAME}/​skills/​{slug}-mode-planner/​SKILL.md
     • ./​.{AGENT_NAME}/​skills/​{slug}-mode-debugger/​SKILL.md
     • ./​.{AGENT_NAME}/​skills/​{slug}-mode-qa-tester/​SKILL.md

5. Make the modes selectable via $switching-modes

   • If ./​.{AGENT_NAME}/​skills/​switching-modes/ exists, update its mode registry to include the three new modes.
     • Prefer editing an explicit “Mode registry” list in ./​.{AGENT_NAME}/​skills/​switching-modes/​SKILL.md (if present).
   • If it does not exist, create a project-local ./​.{AGENT_NAME}/​skills/​switching-modes/​SKILL.md that:
     • writes ./​.{AGENT_NAME}/​state.json with { "mode": "<mode-name>" }
     • documents both baseline modes (if used) and the three new project modes
     • start from assets/​switching-modes-stub.md to avoid bikeshedding
   • After this, switching is done by running:
     • $switching-modes {slug}-mode-planner
     • $switching-modes {slug}-mode-debugger
     • $switching-modes {slug}-mode-qa-tester

6. Validate the generated skills

   • Minimum manual checks:
     • Each generated directory name exactly matches its SKILL frontmatter name.
     • Each generated description is third-person and includes “Use when …”.
   • Optional (if available): run skills-ref validate on each generated skill directory.

Required structure of each generated mode skill

Each mode skill must be a valid Agent Skill.

Frontmatter

Example for planner:

---
name: {slug}-mode-planner
description: Behavioral mode for planning and design work in {slug}. Use when scoping changes, producing design docs, or deciding between approaches.
---

Body

Include these sections (in any order):

• When to use (triggers)
• Operating loop (the step-by-step behavior)
• Question protocol (how to ask questions; allow questions in all modes)
• Output discipline (acceptance criteria + local verification; test-change guardrail)
• Project context pointers (links to memories)

Keep the body concise. If the mode needs lengthy reference material, create references/ files and link them.

Adaptation rules

When adapting templates:

• Prefer links to memories, e.g. ../​memories/​project_overview-skl/​SKILL.md, not copy/​paste.
• Use the project’s terminology: module names, CLI names, test runner names, etc.
• Avoid generic fluff. Encode actionable guardrails, checks, and concrete steps.
• Ensure the mode is usable standalone by a future agent who has access to the memories.

Failure modes and how to handle them

• Unknown {AGENT_NAME}: infer from the local agent folder present (e.g. .claude, .codex). If none exist, ask the user what agent folder to use.
• Mode name collisions: if a target directory already exists, do not overwrite silently. Either append a suffix (e.g. -v2) or ask the user which to keep.
• No reliable test commands: link to suggested_commands-skl and ask the user to confirm the correct test command(s) if missing.