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.