Every bot in this repository follows a three-stage lifecycle:

templates  →  in-progress  →  completed

Location: bots/templates/

Templates are canonical starter assets — import-safe export envelopes with placeholder content.

• Templates are reusable starters only, not active bot work
• Do not modify templates for a specific bot — copy them first
• Template changes must be reflected in BOT_CATALOG.md

Location: bots/in-progress/<bot-name>/

Active bot development happens here. Each bot gets its own kebab-case folder.

mkdir bots/in-progress/my-bot
cp bots/templates/perchance-empty-minimal.json bots/in-progress/my-bot/my-bot-v0.1.0.json

• One folder per bot
• Use kebab-case naming
• Keep iteration artifacts here until the bot is release-ready
• In-progress bots must not be treated as released
• Add a catalog entry to BOT_CATALOG.md when starting work

1. Customize the character row (name, role, behavior)
2. Write customCode as normal JavaScript, then serialize
3. Define initialMessages and shortcutButtons
4. Validate frequently during development

Location: bots/completed/<bot-name>/

Only release-ready, validated bots belong here.

bots/completed/<bot-name>/
├── <bot-name>-v1.0.0.json    # Versioned export artifact
└── RELEASE.md                 # Release notes from RELEASE_TEMPLATE.md

• Export satisfies docs/PERCHANCE_IMPORT_VERIFICATION.md release gate
• node scripts/validate-perchance-export.js <absolute-path> passes
• python -m unittest tests/test-validate-perchance-export.py passes
• Bot folder contains a clearly versioned final export
• RELEASE.md created from bots/completed/RELEASE_TEMPLATE.md
• Scratch/draft artifacts removed from folder
• BOT_CATALOG.md updated with correct lifecycle state, path, status, and verification state
• Lifecycle move and metadata updates committed together

• First completed release: v1.0.0
• Patch increments for compatible fixes: v1.0.1
• Minor for additive compatible updates: v1.1.0
• Major for breaking behavior/contract shifts: v2.0.0

Copy bots/completed/RELEASE_TEMPLATE.md into your bot folder as RELEASE.md and fill in:

• Bot name and export artifact path
• Release version and date
• Verification evidence (validator pass, test pass, checklist applied)
• Promotion context and any known constraints

The repository includes a known-good completed bot:

• Reference Minimal Helper at bots/completed/reference-minimal-helper/
• A minimal, fully importable export with a small valid customCode block
• Use it as a baseline example for completed bots

1. Copy a template to bots/in-progress/<bot-name>/
2. Add an entry to BOT_CATALOG.md with lifecycle state in-progress

1. Pass all promotion requirements (see checklist above)
2. Move bot folder to bots/completed/<bot-name>/
3. Create RELEASE.md with verification evidence
4. Update BOT_CATALOG.md: change lifecycle to completed, update path, set status to ready, set verification to passed

1. Move bot folder to archive/
2. Update BOT_CATALOG.md to reflect retirement
3. Add date-prefixed naming if helpful

• Placing active drafts directly in bots/completed/
• Promoting without running validation commands
• Forgetting to update BOT_CATALOG.md during lifecycle transitions
• Using ambiguous artifact names (final, latest, fixed2)
• Leaving scratch artifacts in completed bot folders