# Awesome Bot Handbook

A practical guide for beginners, teams, and developers, from a first small task to role handoffs and versioned releases. Understand the configuration, then ground each task in materials and acceptance criteria.

## Read for your goal

### Beginner: deliver one result

Understand entry points, finish a fictional exercise, then choose a configuration.

1. [Finish your first small task](https://harzva.github.io/awesome-bot/handbook-start.en.html?path=start)
2. [Understand roles, tasks, and permissions](https://harzva.github.io/awesome-bot/handbook-concepts.en.html?path=start)
3. [Write a checkable task brief](https://harzva.github.io/awesome-bot/handbook-instructions.en.html?path=start)
4. [Choose, download, and import](https://harzva.github.io/awesome-bot/handbook-choose-import.en.html?path=start)
5. [Complete a task through a scenario](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html?path=start)
6. [Locate the failing layer first](https://harzva.github.io/awesome-bot/handbook-troubleshooting.en.html?path=start)

- [Start with a fictional weekly report](https://harzva.github.io/awesome-bot/handbook-start.en.html?path=start#exercise)
- [Next exercise: delivery, testing, and acceptance](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html?path=start#practice-weekly-report)

#### End of reading path: manual checks

This is a reading location, not a claim that the task is complete. Check each item against your actual results and return to the relevant chapter or practice when needed.

- [Check the source of each claim and keep unknowns explicit; the reference is not a wording template.](https://harzva.github.io/awesome-bot/handbook-start.en.html?path=start#accept)
- [Revise one specific gap, then save your task, inputs, and result.](https://harzva.github.io/awesome-bot/handbook-instructions.en.html?path=start#iterate)
- [Distinguish reading, downloading, and host import; if you imported, keep a verification record.](https://harzva.github.io/awesome-bot/handbook-choose-import.en.html?path=start#compare)

### Team: define ownership and handoffs

Coordinate with role ownership, task cards, and named reviewers.

1. [Understand roles, tasks, and permissions](https://harzva.github.io/awesome-bot/handbook-concepts.en.html?path=team)
2. [Make team handoffs traceable](https://harzva.github.io/awesome-bot/handbook-team.en.html?path=team)
3. [Write a checkable task brief](https://harzva.github.io/awesome-bot/handbook-instructions.en.html?path=team)
4. [Complete a task through a scenario](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html?path=team)
5. [Let an Agent read the role it needs](https://harzva.github.io/awesome-bot/handbook-agents.en.html?path=team)
6. [Locate the failing layer first](https://harzva.github.io/awesome-bot/handbook-troubleshooting.en.html?path=team)

- [Practice returning, revising, and accepting a handoff](https://harzva.github.io/awesome-bot/handbook-team.en.html?path=team#handoff)
- [Then hand off a fact table and meeting brief](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html?path=team#practice-customer-meeting)

#### End of reading path: manual checks

This is a reading location, not a claim that the task is complete. Check each item against your actual results and return to the relevant chapter or practice when needed.

- [Name the task owner, recipient, and reviewer.](https://harzva.github.io/awesome-bot/handbook-team.en.html?path=team#owners)
- [Track the return reason, added materials, and accepted version; recheck affected earlier outputs.](https://harzva.github.io/awesome-bot/handbook-team.en.html?path=team#handoff)
- [Keep sources and unknowns in the next role's inputs; review the fact table and final brief separately.](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html?path=team#practice-customer-meeting)

### Developer: read, verify, and contribute

Start with local snapshot verification and a bug-retest exercise, then consult contribution, troubleshooting and file contracts.

1. [Understand roles, tasks, and permissions](https://harzva.github.io/awesome-bot/handbook-concepts.en.html?path=developer)
2. [Complete a task through a scenario](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html?path=developer)
3. [Let an Agent read the role it needs](https://harzva.github.io/awesome-bot/handbook-agents.en.html?path=developer)
4. [Contribute, build, and publish](https://harzva.github.io/awesome-bot/handbook-contribute.en.html?path=developer)
5. [Locate the failing layer first](https://harzva.github.io/awesome-bot/handbook-troubleshooting.en.html?path=developer)
6. [Terms, licenses, and sources](https://harzva.github.io/awesome-bot/handbook-reference.en.html?path=developer)

- [Run the local snapshot success and failure cases](https://harzva.github.io/awesome-bot/handbook-agents.en.html?path=developer#local-lab)
- [Practice a bounded retest plan](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html?path=developer#practice-bug-retest)

#### End of reading path: manual checks

This is a reading location, not a claim that the task is complete. Check each item against your actual results and return to the relevant chapter or practice when needed.

- [The local check prints both PASS lines in order and exits 0; it rejects the altered copy without changing original files.](https://harzva.github.io/awesome-bot/handbook-agents.en.html?path=developer#local-lab)
- [Distinguish a retest plan from a real test result and record missing environment access or evidence.](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html?path=developer#practice-bug-retest)
- [If contributing, check bilingual output and version contracts, and keep reproducible verification records.](https://harzva.github.io/awesome-bot/handbook-contribute.en.html?path=developer#checks)

## Finish your first small task

Use fictional materials to deliver a checkable short report.

### Choose a learning path

Beginners can start with this exercise. Teams can learn the concepts and arrange handoffs. Developers can go directly to the local snapshot lab. In a reading path, the chapter footer leads to the next chapter on that path. There is no need to download the whole catalogue.

- [Beginner: start this exercise](https://harzva.github.io/awesome-bot/handbook-start.en.html?path=start#exercise)
- [Team collaboration](https://harzva.github.io/awesome-bot/handbook-team.en.html?path=team)
- [Developer: local snapshot lab](https://harzva.github.io/awesome-bot/handbook-agents.en.html?path=developer#local-lab)

Before starting, any existing Agent that handles text can do this exercise; no account purchase is required first. Copy for Agent copies context, download saves a file, and import asks a host to read configuration. These are separate actions. Use the import entry available in your actual host.

### Write a fictional weekly report

Copy the entire “Practice task and materials” block below into your existing text-capable Agent to produce the first weekly report draft. This step needs no download, import, real mailbox or project account. Optionally use Status Report Writer role context, subject to the Agent’s existing instructions.

#### Practice task and materials

```text
Write a weekly status draft of no more than 120 words from these fictional records.
Goal: deliver a registration page on Friday.
Record A (Wednesday): form page complete; not tested.
Record B (Thursday): desktop tests passed; mobile tests not started.
Record C (Thursday): copy awaits Alex's approval, expected Friday morning.
Output: goal, verified progress, pending acceptance, blockers, next steps.
Acceptance: cite A/B/C; do not equate page completion with full acceptance; mark missing owners as unconfirmed.
Boundary: draft only. Do not publish or contact anyone.
```

The following is a prepared teaching reference, not an actual Bot run. Wording may vary, but preserve the five items and evidence limits. Numbered citations identify the original records.

#### Teaching reference excerpt

```text
Goal: deliver the registration page on Friday.
Verified progress: form complete [A]; desktop tests passed [B].
Pending acceptance: mobile tests not started [B].
Blocker: copy awaits Alex, expected Friday morning [C].
Next: arrange mobile testing (owner unconfirmed), follow up on copy, then review acceptance.
```

Incorrect: “The registration page has passed full acceptance.” Targeted revision prompt: “Revise only this sentence: desktop passed; mobile not started; copy pending. Cite B/C and retain other checked content.”

### Check and revise the result

1. Check all five sections and distinguish desktop from mobile testing.
2. Match completion claims to records; remove unsupported sentences or mark them unknown.
3. Name precise gaps, ask the Agent to revise the draft, and save both the task and result.

### Use your own materials

Replace the goal, records, and acceptance criteria, then try a small sanitized sample. Before reading real files or accounts, confirm tools and task authorization in the host. One successful exercise does not certify every account task.

- [Find Status Report Writer](https://harzva.github.io/awesome-bot/?lang=en&bot=awesome%2Fstatus-report-writer)
- [Choose and import](https://harzva.github.io/awesome-bot/handbook-choose-import.en.html)

### Sources

Sources checked: 2026-10-25

- [First-use guide](https://github.com/Harzva/awesome-bot/blob/main/START_HERE.en.md)
- [Exercise role source](https://github.com/Harzva/awesome-bot/blob/main/data/entries/status-report-writer.json)

## Understand roles, tasks, and permissions

Recognize entry points and files to choose the right next step.

### What the site contains

The catalogue contains 371 configurations: 315 roles and 56 task workflows, plus 17044 Shared Bots source links. These are coverage counts, not installations or task success rates.

| Resource | Purpose | Next step |
| --- | --- | --- |
| Role configuration | Ongoing responsibility and method | Choose by responsibility |
| Task workflow | Steps toward an output | Supply materials and start a task |
| Shared Bots | Original-site or source-file links | Read requirements at the source |
| Project reference | External software and architecture | Evaluate integration separately |

### Instructions and runtime capabilities

Configurations describe roles and needs. Models handle generation and reasoning. Hosts provide environments, tools, and account authorization. Reading email is an input need, not an automatic mailbox connection.

1. Read inputs, outputs, and prerequisites.
2. Check actual host models, tools, and accounts.
3. If capabilities are missing, supply available materials or list the gaps.

### Configurations do not transfer private state

Configurations exclude conversations, learned memory, model keys, live account connections, and running tasks. Ordinary exports disable tools and containers. In an empty library, the host may select the first Bot as primary with management capabilities under its rules. Check primary identity and permission behavior in the import preview.

### Read verification claims

Source review establishes provenance. Format and export tests check repository contracts. Real-account tasks need separate evidence of inputs, execution, and results. The site has not individually certified every role's account tasks.

- [Integration contract](https://github.com/Harzva/awesome-bot/blob/main/INTEGRATION.md)

### Sources

Sources checked: 2026-10-25

- [Project overview](https://github.com/Harzva/awesome-bot/blob/main/README.md)
- [Host integration contract](https://github.com/Harzva/awesome-bot/blob/main/INTEGRATION.md)
- [Market aggregation guide](https://github.com/Harzva/awesome-bot/blob/main/docs/market-aggregation.md)

## Choose, download, and import

Check responsibilities, sources, and configuration before host preview and confirmation.

### Start with the output you need

1. Search for a goal such as meeting preparation, bug retesting, or a weekly report.
2. Open details and compare responsibility, inputs, outputs, skills, sources, and permission needs.
3. Start with one role and define a handoff before adding another.
4. Check body language and platform assumptions, especially in English source adaptations.

Choose bot-role for an ongoing responsibility and method; choose task-workflow for a step template organized around an output, reusable as needed. Preview and confirm either in the host, then check tools, accounts, and human handoffs. A workflow template does not itself provide automatic orchestration or a verified runtime state; assess the actual output against acceptance criteria.

### Choose the download type

| Situation | Recommendation |
| --- | --- |
| First use | One role or a small scenario download |
| Need English content | Choose its configuration in English mode |
| Large collection | Use release parts with at most 200 Bots per Fleet file |
| Only need Agent context | Use Copy for Agent or one role context file |

Shared Bots are source links, not installable configurations from this site. Identical names do not prove identity; compare author, platform, and URL.

### Preview and confirm in the host

1. Keep the file with its role ID, version, language, and digest.
2. Use the host's current configuration import entry, select the Fleet file, and read the preview and confirmation.
3. Check new names, collision handling, and existing primary Bot state.
4. After confirmation, separately configure models, tools, and accounts, then start an explicit task.

The repository README documents a Settings → Data & Sync → Import configuration example. Follow the entry in your current host version. Downloading and importing do not themselves start tasks or environments.

### Check after import

- Compare responsibility by ID rather than name alone.
- Record actual host-returned Bot IDs for later upgrade reconciliation.
- Accept a fictional short task before supplying real materials.

- [Configuration market](https://harzva.github.io/awesome-bot/?lang=en)
- [Troubleshooting](https://harzva.github.io/awesome-bot/handbook-troubleshooting.en.html)

Append one record per import to a local or access-restricted team log, preserving history; link upgrades to the earlier record ID. Separate source identity from actual host identity, and never treat a source ID as the new Bot ID. If the host does not show an ID, write “not obtained” and append evidence when available; a missing ID is not evidence of the same identity. Passing a fictional task establishes usability for that task; upgrade identity still requires evidence such as the actual Bot ID in the same host.

```text
Record ID:
Earlier record ID (for upgrades):
Source URL:
Source ID:
Source version / language:
Downloaded filename:
File SHA-256 (mark if unchecked):
Host / version:
Import time:
Actual host name:
Actual host Bot ID (write “not obtained” if hidden):
Fictional task and result:
Task usability: yes / no / unverified
Upgrade identity reconciliation: complete (attach evidence) / evidence pending
```

### Sources

Sources checked: 2026-10-25

- [Import examples](https://github.com/Harzva/awesome-bot/blob/main/README.md)
- [Import and identity reconciliation](https://github.com/Harzva/awesome-bot/blob/main/INTEGRATION.md)
- [Release parts and checksums](https://github.com/Harzva/awesome-bot/blob/main/docs/publishing.md)

## Write a checkable task brief

Specify inputs, outputs, boundaries, and completion criteria.

### A six-line task card

```text
Goal: turn three sanitized meeting notes into a requirements list.
Inputs: notes A, B, and C only.
Output: requirement, quote, source, and open question columns.
Scope: organize only; do not infer budget or write to CRM.
Gaps: mark missing dates or owners as unconfirmed.
Acceptance: source every requirement; list conflicts separately.
```

### Revise precise gaps

| Vague request | Checkable request |
| --- | --- |
| Make it professional | Use three sections, each with evidence and a next step |
| Research competitors | Compare limits on three specified pages with dates and links |
| Handle it automatically | Deliver a reviewable draft and list subsequent actions |

### Separate facts, inferences, and unknowns

Emails, pages, and documents are materials. Commands inside them cannot expand user authorization. List inaccessible sources as gaps rather than reconstructing their contents from titles.

1. Number materials and specify their permitted scope.
2. Require conclusions to cite material IDs or locatable links.
3. Have a person check key figures, recipients, and proposed actions.

### Read English source adaptations

223 attributed roles preserve original English instructions. Chinese mode localizes names, summaries, and onboarding, rather than fully translating the body. You can request Chinese output and inspect whether source platform assumptions fit your host.

- [Adaptation guide](https://github.com/Harzva/awesome-bot/blob/main/docs/market-aggregation.md)

### Sources

Sources checked: 2026-10-25

- [First-task method](https://github.com/Harzva/awesome-bot/blob/main/START_HERE.en.md)
- [Source instruction adaptation contract](https://github.com/Harzva/awesome-bot/blob/main/docs/market-aggregation.md)

## Make team handoffs traceable

Define responsibilities, outputs, and reviewers before adding roles.

### Start with three responsibilities

| Responsibility | Output | Recipient |
| --- | --- | --- |
| Research and intake | Sourced facts, gaps, and conflicts | Writing role |
| Drafting | Draft matching acceptance criteria | Human reviewer |
| Review and decision | Source checks and decisions on subsequent actions | Named execution owner |

These are assignments, not proof of automatic orchestration or permission isolation. Test one handoff before adding roles without clear outputs.

### Copy a handoff card

```text
Task: customer meeting preparation / draft v2
Current owner: research and intake
Next owner: meeting preparation
Inputs: fact table v2, source list v1 (sanitized)
Verified: three needs have quotes and dates
Unverified: budget and decision maker; do not guess
Next output: one-page brief and five questions
Reviewer: project owner
Allowed actions: read these files, write a draft; no customer contact
Stop condition: missing sources or unexplained conflicts
```

Practice a manual handoff with Qinghe Studio. All materials below are fictional. Write drafts only; do not contact the customer. The recipient explicitly fills in the receipt; this does not imply a background state machine in the host.

```text
A | Profile: Qinghe Studio, a 12-person customer service team.
B | Discussion on 2026-10-20: wants a month-end ticket summary; budget and decision maker unconfirmed.
C | Product validation: CSV import verified; real-time sync unverified.
Fact table v1: includes A/B, omits C.
Receipt: return v1; product validation limits C missing; pause brief drafting.
Fact table v2: add C; budget, decision maker, and real-time sync remain unconfirmed.
Old brief: based on v1; mark “review pending” and hold circulation.
Reviewer Lee's receipt: decision to accept fact table v2; recheck the draft brief against v2 before resubmitting.
```

Stop for missing sources, unclear versions, or unexplained conflicts. Resume after materials are supplied and reviewer Lee names the accepted version. Mark old outputs for review and recheck them before the next handoff. Accepting a fact table does not accept the brief or product.

### Shared configuration is not shared memory

Shared configurations transfer definitions and methods, without the creator's conversations, learned memory, accounts, or keys. Supply project context in a versioned sanitized packet with an explicit sharing scope, for use in the recipient's authorized environment.

1. Keep stable methods in configuration and project facts in a packet.
2. List exact files and versions rather than assuming shared background.
3. Confirm materials are readable and review the output before proceeding.

### Use gitopsbot as a coordination example

The bilingual gitopsbot playbook covers GitHub-to-Feishu routing, signatures, deduplication, receipts, and recovery. Start with a table of repositories, events, destination groups, sender, and access gaps. Downloading the role does not create a listener, connect accounts, or grant group-send permission.

- [Open gitopsbot](https://harzva.github.io/awesome-bot/?lang=en&bot=awesome%2Fgitopsbot)
- [Setup and operations playbook](https://github.com/Harzva/awesome-bot/blob/main/docs/gitopsbot-playbook.en.md)

### Sources

Sources checked: 2026-10-25

- [Scenarios and human handoffs](https://github.com/Harzva/awesome-bot/blob/main/README.md)
- [State and permission contract](https://github.com/Harzva/awesome-bot/blob/main/INTEGRATION.md)
- [gitopsbot operations method](https://github.com/Harzva/awesome-bot/blob/main/docs/gitopsbot-playbook.en.md)

## Complete a task through a scenario

Organize one task around materials, steps, outputs, and acceptance.

### Choose a scenario by its output

The site offers 5 bilingual scenarios: customer meetings, weekly reports, bug retesting, feedback-to-requirements, and product launches. Each provides a small set of relevant roles and a first task to copy.

Review the roles and original tasks, then try the fictional materials below. All five reference outputs are prepared teaching examples. Check the evidence; the wording need not match.

- [Practice: from a fact table to a meeting brief](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html#practice-customer-meeting)
- [Practice: separate delivery, testing, and acceptance](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html#practice-weekly-report)
- [Practice: plan retesting without an environment](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html#practice-bug-retest)
- [Practice: turn duplicate and conflicting feedback into candidates](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html#practice-feedback-to-requirements)
- [Practice: hold a launch when evidence is missing](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html#practice-product-launch)

### Scenario materials and task cards

#### Reproduce a bug and plan retesting

Create a minimal reproduction, then check affected key paths and release blockers.

##### Inputs

- Issue description, expected behavior, frequency and minimal input
- Specified code or testable build, platform and environment details
- Permitted test environment, data, accounts and interface
- Core user tasks, release criteria and known fixes

##### Expected outputs

- Minimal reproduction steps, logs and environment details
- Confirmed findings and diagnostic hypotheses still needing validation
- Key-path check records, release blockers and retest order

##### 1. [Bug Reproduction](https://harzva.github.io/awesome-bot/?lang=en&scenario=bug-retest&bot=awesome%2Fbug-reproduction)

```text
Help reproduce this bug first. Issue and expected behavior: [fill in]; specified build and platform: [fill in]; minimal input or sample: [provide authorized data]; permitted test environment and operation scope: [fill in]. Record actual versus expected differences, progressively reduce triggering conditions, retain logs and environment details, and distinguish confirmed causes from hypotheses. If necessary tools or an environment are unavailable, explain the gap and provide steps I can execute; do not claim to have reproduced it.
```

Handoff: I will verify the reproduction evidence and pass repeatable steps, the impact scope and confirmed fixes to Startup QA Bot.

##### 2. [Startup QA Bot](https://harzva.github.io/awesome-bot/?lang=en&scenario=bug-retest&bot=awesome%2Fgrok-startup-qa-bot)

```text
Use the following verified bug reproduction and fix information to check affected core user paths and plan retesting. Reproduction and fixes: [paste]; testable build and core tasks: [fill in]; release criteria, test accounts and authorized interface operations: [fill in]. Record real findings on normal, empty and error paths, then list release blockers and a retest method for each. Explicitly mark unexecuted or unverified items as awaiting checks, and do not access unauthorized environments.
```

Handoff: The release owner and I will review check evidence, blockers and retest results to decide whether release criteria are met.

[View in market](https://harzva.github.io/awesome-bot/?lang=en&scenario=bug-retest) · [Download scenario configuration](https://harzva.github.io/awesome-bot/exports/en/scenario-bug-retest.fleet.json) · [Try the practice](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html#practice-bug-retest)

#### Prepare a customer meeting

Verify company background, then organize the agenda, evidence and questions to resolve in this meeting.

##### Inputs

- Target company, research purpose and product fit criteria
- Authorized company materials, sources and communication history
- Meeting goals, participants, product materials and permitted commitment scope

##### Expected outputs

- Company research brief with sources and dates
- Need signals that separate facts from hypotheses
- One-page meeting brief, agenda, questions and preparation tasks

##### 1. [Account Research Specialist](https://harzva.github.io/awesome-bot/?lang=en&scenario=customer-meeting&bot=awesome%2Faccount-research-specialist)

```text
I need a company research brief for a customer meeting. Target company and research purpose: [fill in]; product and fit criteria: [fill in]; authorized materials and sources: [paste or provide an authorized location]. Verify the company entity, business and recent changes, recording sources and dates. Separate facts, need signals and buying hypotheses. If materials are insufficient, list missing information first, and do not claim access to sources that are not connected.
```

Handoff: I will review the brief and pass confirmed background, need signals and hypotheses to verify to Meeting Prep Buddy.

##### 2. [Meeting Prep Buddy](https://harzva.github.io/awesome-bot/?lang=en&scenario=customer-meeting&bot=awesome%2Fmeeting-prep-buddy)

```text
Use the following reviewed company research, communication history, participants and meeting goals to prepare a one-page brief, agenda, key questions and preparation tasks. Company research brief: [paste]; participants and meeting goals: [fill in]; product evidence and permitted commitments: [fill in]. Separate customer facts, our hypotheses and commitments requiring internal confirmation. Do not send messages or schedule meetings on my behalf.
```

Handoff: I will review the meeting materials and confirm the commitment scope before using them in the actual meeting.

[View in market](https://harzva.github.io/awesome-bot/?lang=en&scenario=customer-meeting) · [Download scenario configuration](https://harzva.github.io/awesome-bot/exports/en/scenario-customer-meeting.fleet.json) · [Try the practice](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html#practice-customer-meeting)

#### Turn feedback into requirements

Identify feedback themes and user impact, then consolidate a traceable requirements list with questions to clarify.

##### Inputs

- Authorized feedback and tickets with timestamps and sources
- Product and user segments, known issues and recent changes
- Existing requirements repository and requirement links

##### Expected outputs

- Feedback themes and user tasks retaining original evidence
- Deduplicated requirements list and impact scope
- Validation suggestions and clarification questions without development schedule commitments

##### 1. [Product Feedback Analyst](https://harzva.github.io/awesome-bot/?lang=en&scenario=feedback-to-requirements&bot=awesome%2Fproduct-feedback-analyst)

```text
Analyze this authorized feedback batch. Feedback records, sources and timestamps: [paste]; product and user segments: [fill in]; known issues and recent changes: [fill in]. Group themes by user context, goal, obstacle and impact. Retain original evidence and contradictory feedback, and describe sample coverage and missing information. Suggest verifiable improvements without promising a development schedule.
```

Handoff: I will check themes against the original records and pass confirmed themes and evidence to Feature Request Tracker.

##### 2. [Feature Request Tracker](https://harzva.github.io/awesome-bot/?lang=en&scenario=feedback-to-requirements&bot=awesome%2Ffeature-request-tracker)

```text
Turn the following reviewed feedback themes and original evidence into a requirements list. Themes and evidence: [paste]; existing requirements repository: [provide authorized records]; customer and product segments: [fill in]. Merge duplicate requests and link existing requirements, retaining specific problem contexts, impact scope and clarification questions. Separate requirement facts from prioritization suggestions. Do not promise a schedule on behalf of the product owner or modify the requirements repository.
```

Handoff: The product owner and I will review requirements and verify missing details before deciding priorities and whether to add records.

[View in market](https://harzva.github.io/awesome-bot/?lang=en&scenario=feedback-to-requirements) · [Download scenario configuration](https://harzva.github.io/awesome-bot/exports/en/scenario-feedback-to-requirements.fleet.json) · [Try the practice](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html#practice-feedback-to-requirements)

#### Prepare a product launch

Build positioning from customer problems and product evidence, then work backward to schedule assets, reviews and channel publication.

##### Inputs

- Target customers, need evidence and alternatives
- Product capabilities, limitations and demonstrable differences
- Launch goals, deadlines, existing assets and channels
- Production and review owners and immovable milestones

##### Expected outputs

- Positioning, value statements and an audience messaging matrix
- Launch content requirements and validation plan
- Marketing calendar, dependency conflicts and checkpoints

##### 1. [Product Marketer](https://harzva.github.io/awesome-bot/?lang=en&scenario=product-launch&bot=awesome%2Fgrok-product-marketer)

```text
Prepare a positioning draft for a product launch. Target customers and need evidence: [fill in]; product capabilities, limitations and evidence of differences: [fill in]; launch goals and existing assets: [fill in]. Map customer tasks and alternatives to demonstrable value, and organize audience messages and content requirements. Keep unproven claims as hypotheses and list follow-up validation. Do not invent customer testimonials or performance results.
```

Handoff: I will review the positioning and evidence, then pass confirmed audience messages, content requirements and validation plans to Marketing Calendar Owner.

##### 2. [Marketing Calendar Owner](https://harzva.github.io/awesome-bot/?lang=en&scenario=product-launch&bot=awesome%2Fmarketing-calendar-owner)

```text
Work backward from the following reviewed launch content requirements to prepare a marketing calendar. Positioning and content requirements: [paste]; launch goals and deadlines: [fill in]; channels and asset list: [fill in]; production and review owners and fixed milestones: [fill in]. Identify production, review and channel dependencies, resource conflicts and gaps, recording an owner and checkpoint for each item. Prepare a reviewable plan only. Do not publish content, send messages or promise unconfirmed dates on my behalf.
```

Handoff: The relevant owners and I will confirm the calendar, resources and review arrangements before carrying out publication through authorized processes.

[View in market](https://harzva.github.io/awesome-bot/?lang=en&scenario=product-launch) · [Download scenario configuration](https://harzva.github.io/awesome-bot/exports/en/scenario-product-launch.fleet.json) · [Try the practice](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html#practice-product-launch)

#### Write an evidence-backed weekly report

Use one Bot to turn project artifacts, verification and blockers into a clear status-report draft.

##### Inputs

- This week's reporting period, project goals and milestones
- Completed artifacts, test results and acceptance records
- Ongoing work, blockers and plan changes
- Next-phase plan, pending decisions and responsible owners

##### Expected outputs

- Weekly report draft separating delivered work, pending acceptance, ongoing work and blockers
- Evidence-backed risk explanations and decision requests
- Next-phase actions and responsible owners

##### 1. [Status Report Writer](https://harzva.github.io/awesome-bot/?lang=en&scenario=weekly-report&bot=awesome%2Fstatus-report-writer)

```text
Write this week's status-report draft from the following project facts. Reporting period, goals and milestones: [fill in]; artifacts, tests and acceptance records: [paste]; ongoing work, blockers and plan changes: [fill in]; next-phase actions and pending decisions: [fill in]. Separate delivered work, pending acceptance, ongoing work and blocked items. Keep evidence for conclusions and explain deviations, risks and required decisions. Leave unsupported progress unknown, and do not equate passing tests with business acceptance.
```

Handoff: I will verify the evidence, owners and decision requests, revise and confirm the draft, then send it to the intended readers.

[View in market](https://harzva.github.io/awesome-bot/?lang=en&scenario=weekly-report) · [Download scenario configuration](https://harzva.github.io/awesome-bot/exports/en/scenario-weekly-report.fleet.json) · [Try the practice](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html#practice-weekly-report)

### Practice: from a fact table to a meeting brief

For beginners and team handoffs. All materials below are fictional. The reference output is a prepared teaching example, not a Bot run. Copy the materials, build a sourced fact table, then prepare a one-page meeting brief and five questions. Produce an internal draft without customer commitments.

#### Practice task and materials

```text
Task: act as the Account Research Specialist. Use only the fictional materials below to prepare a fact table for meeting preparation.
Output: facts, source IDs and dates, need signals, and assumptions to verify. Mark absent dates, budget and decision-maker as unknown; do not infer purchase intent.
Boundary: internal draft only. Do not contact customers, quote prices or promise unverified capabilities.

Fictional materials:
A | Company profile, 2026-10-19: Qinghe Studio is a customer service team of 12.
B | Conversation, 2026-10-20: wants month-end ticket summaries; budget and decision-maker unknown.
C | Internal demo, 2026-10-21: only CSV import verified; real-time sync unverified.
D | Meeting goal, 2026-10-23: clarify summary definitions, data sources, and trial conditions.
E | Attendees: our account manager; customer attendees and responsibilities unconfirmed.
F | Scope: use A-E only; infer no purchase intent, price, or real-time sync commitment.
```

1. Give A-F to Account Research Specialist (awesome/account-research-specialist): build a table of facts, source dates, need signals, and assumptions to verify.
2. After human review, pass the fact table, B/C, and unknowns to Meeting Prep Buddy (awesome/meeting-prep-buddy). Request one page with an agenda, exactly five questions, and material tasks.
3. Have a human review commitment boundaries and save the draft. Attendees confirm questions and tasks; do not send it automatically.

#### Teaching reference excerpt

```text
Background: Qinghe Studio, a customer service team of 12 (A, 2026-10-19).
Goal and agenda: clarify month-end ticket summaries (B); definitions, data, then trial conditions (D).
Capability boundary: fictional internal record verifies CSV import only; sync unverified (C); budget and decision-maker unknown (B).
Five questions: Which fields? Which date defines the month? Where is data exported? Who decides on a trial? What budget and evaluation criteria apply?
Material tasks: our account manager prepares a CSV sample and demo scope; customer attendees and responsibilities unconfirmed (C/E).
```

1. Keep each source ID. Copy supplied dates and mark absent dates as not provided. Separate facts, demand signals and hypotheses; wanting a monthly summary is not purchase intent.
2. Check the one-page draft includes an agenda, five questions, and material tasks covering definitions, dates, sources, decision-making, and budget.
3. Retain unknown budget and decision-maker, and unverified sync. Include no external commitment or sent-message claim.

#### Revision request

```text
Repair only gaps: keep the reviewed fact table. Replace any sync-support claim with "unverified (C)"; add missing sources or questions. Return affected rows and the revised brief without inventing customer information. If a reviewer finds a gap, return it to the role that produced it. A human reviews the revision before handoff or saving; there is no automatic routing.
```

- [Open scenario task cards](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html#scenario-customer-meeting)
- [View scenario roles in the market](https://harzva.github.io/awesome-bot/?lang=en&scenario=customer-meeting)

### Practice: separate delivery, testing, and acceptance

For beginners and team reporting. All materials are fictional. The reference is a prepared teaching example, not a Bot run. Copy the records and draft the report for 2026-10-19 through 2026-10-23 with evidence IDs. Keep earlier work and technical tests separate from current business acceptance.

#### Practice task and materials

```text
Task: act as the Status Report Writer. Use only the fictional records below to draft the report for 2026-10-19 through 2026-10-23.
Output: current delivery, technical validation, business acceptance pending, earlier work, and blockers/next steps. Cite source IDs for every status. Mark missing owners and dates unknown and request assignment.
Boundary: do not equate technical tests with business acceptance or earlier work with current delivery. Draft only; do not send.

Fictional materials:
A | Weekly goal: deliver a registration-page draft on 2026-10-23; arrange business acceptance separately.
B | 2026-10-20: Chen submitted page draft v0.3 with a delivery record.
C | 2026-10-21: technical record shows 8 desktop tests passed; mobile testing not started.
D | 2026-10-23: business acceptance still pending; no approval record supplied.
E | 2026-10-16: registration field list completed last week; exclude from new weekly deliveries.
F | 2026-10-22: legal copy pending; owner and response date unknown.
G | Next: Chen plans mobile tests on 2026-10-26; copy owner awaits assignment.
```

1. Give records to Status Report Writer (awesome/status-report-writer): group current delivery, technical validation, business acceptance pending, earlier work, and blockers/next steps, citing IDs.
2. The report owner checks dates and evidence, flags the copy blocker as an assignment request, and sends only after confirmation.

#### Teaching reference excerpt

```text
Period: 2026-10-19 through 2026-10-23; page draft v0.3 delivered (A/B).
Technical validation: 8 desktop tests passed; mobile untested (C).
Business status: acceptance pending (D); do not mark the whole project complete.
Earlier work: field list completed on 2026-10-16, background only (E).
Blocker/action: assign a copy owner and response date (F); Chen plans mobile tests on 2026-10-26 (G).
```

1. Count B as this week's delivery and E as earlier work; distinguish reporting dates from next-step dates.
2. Limit the count of 8 to desktop technical tests; preserve separate mobile and business acceptance states.
3. Source every status. Keep F owner/date unknown and request assignment without inventing a name.

#### Revision request

```text
Repair only gaps: retain sourced delivery records. Split any "fully accepted" claim into technical validation (C) and pending acceptance (D), move E to background, and add an assignment request for F. Return changed paragraphs only. If a reviewer finds a gap, return it to the role that produced it. A human reviews the revision before handoff or saving; there is no automatic routing.
```

- [Open scenario task cards](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html#scenario-weekly-report)
- [View scenario roles in the market](https://harzva.github.io/awesome-bot/?lang=en&scenario=weekly-report)

### Practice: plan retesting without an environment

For developers and team handoffs. Browser feedback, logs, and versions below are fictional. The reference is a prepared teaching example, not a Bot run. There is no real test environment. Practice planning and evidence classification only; execution remains pending, with no reproduced or fixed claims.

#### Practice task and materials

```text
Task: act as Bug Reproduction. Use only the fictional materials below to write a minimal reproduction plan. There is no real test environment; do not run tests.
Output: separate reports, log clues and fix hypotheses. Plan single-click controls, double-click cases and repeated trials. Leave fields for expected/actual outcomes, trial counts, build, environment and evidence blank, and list missing environment details.
Boundary: mark execution pending throughout. Two log lines do not prove a root cause; claim no reproduction, repair or release readiness.

Fictional materials:
A | Fictional report, 2026-10-21: Chrome 129 / macOS 14, draft v0.3; two clicks on Submit show two registrations.
B | Expected: one submission intent creates one entry; reporter says intermittent, frequency unmeasured.
C | Fictional log: 10:02:01 POST /signup 201; 10:02:01 POST /signup 201; no request IDs.
D | Minimal input: name "Test A", email test@example.invalid; planning only.
E | Developer note: candidate v0.3.1 disables the button during submission; no fix verification record.
F | Core paths: normal, blank, failed-request retry; no real environment, account, or actual build supplied.
G | Release conditions: repeatable baseline evidence, candidate retest under matching conditions, and three path records reviewed by an owner.
```

1. Give records to Bug Reproduction (awesome/bug-reproduction): classify A/B as reports, C as a fictional log clue, and E as a fix hypothesis. Plan a single-click control, double-click case, and repeated trials; list missing environment details.
2. After human review, pass the plan, unverified hypotheses, and blank execution fields to Startup QA Bot (awesome/grok-startup-qa-bot). Sequence normal, blank, retry, and candidate checks, all pending.
3. A real executor obtains an authorized environment and completes records separately. The release owner decides from real evidence, not this fictional example.

#### Teaching reference excerpt

```text
Classification: A/B are reports, C is a fictional log clue, E is a candidate fix note; none proves a cause.
Plan: fix input D; run baseline single-click control and double-click trials, recording each outcome; retest the candidate under matching conditions.
Checks: normal, blank, then failed-request retry; all currently pending (F).
Real executor fills: name___ date___ build/environment___ trials___ expected/actual___ log/screenshot location___.
Completion: repeatable baseline evidence, candidate results, and three path records complete; failures resolved and release owner signs off (G).
```

1. Require a single-click control, double-click cases, and recorded trial counts. Two 201 lines alone establish neither duplicate entries nor root cause.
2. Include pending baseline, candidate, and three-path checks, with executor, date, environment, build, result, and evidence fields.
3. Without real execution, claim neither reproduction, repair, nor release readiness. Real completion requires G and reviewed execution records.

#### Revision request

```text
Repair only gaps: keep the plan. Replace unsupported reproduced/fixed claims with "pending real execution". Add only missing controls, paths, or record fields and identify required real evidence; generate no execution results. If a reviewer finds a gap, return it to the role that produced it. A human reviews the revision before handoff or saving; there is no automatic routing.
```

- [Open scenario task cards](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html#scenario-bug-retest)
- [View scenario roles in the market](https://harzva.github.io/awesome-bot/?lang=en&scenario=bug-retest)

### Practice: turn duplicate and conflicting feedback into candidates

For team handoffs; beginners can start by checking sources. All materials are fictional. The reference is a prepared teaching example, not a Bot run. Copy the records to produce traceable requirement candidates with unconfirmed priorities. A small sample cannot establish majority demand; promise no schedule and do not write to a backlog.

#### Practice task and materials

```text
Task: act as the Product Feedback Analyst. Use only the fictional records below to organize feedback themes for human review before handoff to Feature Request Tracker.
Output: themes, user tasks, source IDs and quotes, deduplication, conflicts and sample gaps. Count A/B as one incident; retain C/E as separate issues from one user.
Boundary: do not turn a three-user sample into majority demand, set priorities, promise dates or edit a backlog.

Fictional materials:
A | Ticket T01, 2026-10-19, U1/admin: weekly CSV export takes too many steps; wants one-click export.
B | Email M01, 2026-10-20, U1: forwards T01 again, the same incident.
C | Ticket T02, 2026-10-20, U2/admin: wants all members shown by default.
D | Interview I01, 2026-10-21, U3/member: opposes showing all members by default due to roster privacy.
E | Ticket T03, 2026-10-22, U2: cannot find CSV export; a different issue from T02.
F | Existing R07: simplify CSV export, awaiting review; recent change only renamed navigation.
G | Coverage: 3 users, 2 roles; total population, representativeness, impact frequency, and priorities unknown.
```

1. Start with Product Feedback Analyst (awesome/product-feedback-analyst): preserve IDs and quotes, deduplicate A/B as one incident, separate export tasks from conflicting member-visibility requests, and state sample gaps.
2. After human review, pass themes to Feature Request Tracker (awesome/feature-request-tracker): link A/E to R07, keep C/E distinct despite the shared user, and record candidates, sources, conflicts, validation, and unconfirmed priorities.
3. The product owner verifies impact and access rules before deciding priorities and backlog entry; retain open questions.

#### Teaching reference excerpt

```text
Deduplication: A/B are one incident with two sources; do not count two users.
R07 candidate addition: simplify and clarify CSV export, A/E from 2 users; retain both step-count and discoverability issues.
Candidate N02: clarify member visibility by role; C requests all-visible, D opposes it; do not default to all-visible.
Validation: walk through export; confirm visibility and access policy with both roles, then measure impact frequency.
Priority: R07/N02 await product-owner confirmation; 3 users do not represent a majority (G); promise no development date.
```

1. Count A/B as one incident while retaining both sources; do not deduplicate C/E, different issues from one user.
2. Give every candidate an ID, sources, and validation method; link A/E to R07 instead of creating an unsupported duplicate.
3. Retain the C/D conflict, three-user coverage limit, and unconfirmed priorities; claim neither majority demand nor a scheduled feature.

#### Revision request

```text
Repair only gaps: retain traceable candidates. Correct the A/B count, add missing C/D opposition or sources, and mark unsupported priorities unconfirmed. Return affected candidates and deduplication notes only. If a reviewer finds a gap, return it to the role that produced it. A human reviews the revision before handoff or saving; there is no automatic routing.
```

- [Open scenario task cards](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html#scenario-feedback-to-requirements)
- [View scenario roles in the market](https://harzva.github.io/awesome-bot/?lang=en&scenario=feedback-to-requirements)

### Practice: hold a launch when evidence is missing

For team handoffs and product-owner review. All materials are fictional. The reference is a prepared teaching example, not a Bot run. Copy the materials to prepare positioning and a calendar with dependencies. Include failed checks and unknown metrics; record a human hold decision without inventing a live launch.

#### Practice task and materials

```text
Task: act as the Product Marketer. Use only the fictional materials below to draft positioning for human review before scheduling.
Output: audience, customer task, evidenced capabilities, value hypotheses, content needs and open validation items. Cite source IDs for each claim and retain failed checks and the human hold.
Boundary: invent no metrics, testimonials or live-launch status. Do not confirm a launch date or publish.

Fictional materials:
A | Audience: small event teams; 3 interviews mention time spent organizing registrations, not a representative sample.
B | Product evidence, 2026-10-21: demo verifies CSV export only; time-saving percentage and conversion rate unknown.
C | Quality record, 2026-10-22: mobile failed-request retry check failed; no retest result yet.
D | Target: introduction page and email proposed for 2026-10-28; date unconfirmed, not live.
E | Assets: page draft ready; email copy incomplete; no authorization for customer testimonials.
F | Owners: Lin creates, Zhou reviews; review slot fixed on 2026-10-27; email depends on page approval.
G | Human decision, 2026-10-23: hold external release; resume only with passing C retest evidence, approved assets, and owners reconfirming the date.
```

1. Start with Product Marketer (awesome/grok-product-marketer): draft audience positioning from A/B, separating demonstrated capability from value hypotheses. Include no invented metrics or testimonials; retain C/G gates.
2. After human review, pass it to Marketing Calendar Owner (awesome/marketing-calendar-owner): work backward through creation, review, and channel checkpoints, with F dependencies and fixed slot; keep 2026-10-28 as an unconfirmed target.
3. A human maintains the hold under G. Once real evidence is complete, owners review the date again and execute publication under separate authorization.

#### Teaching reference excerpt

```text
Positioning draft: a CSV export workflow for small event teams (A/B); time savings remain a hypothesis.
Copy boundary: no saving percentage, conversion uplift, or customer testimonial (B/E).
Calendar: Lin completes email draft, Zhou reviews page and email on 2026-10-27, then channel checks; email depends on page approval (E/F).
Status: human hold (G); mobile retry failed (C); 2026-10-28 awaits reconfirmation, not live (D).
Resume evidence: passing C retest record, both asset approvals, and an owner-confirmed date; unknown outcome metrics need a separate validation plan.
```

1. Source value claims to A/B or mark them hypotheses. Invent no missing metrics and include no unauthorized testimonials.
2. Include creation/review owners, the fixed 2026-10-27 checkpoint, and the email dependency; do not turn the target into a promise.
3. State the failed C check, human hold G, and all three resume-evidence requirements; a draft plan is not a live launch.

#### Revision request

```text
Repair only gaps: retain sourced positioning and calendar entries. Remove unsupported metrics and add missing C/G gates or dependencies. Return changed lines and outstanding resume evidence; do not lift the hold or mark the launch live. If a reviewer finds a gap, return it to the role that produced it. A human reviews the revision before handoff or saving; there is no automatic routing.
```

- [Open scenario task cards](https://harzva.github.io/awesome-bot/handbook-scenarios.en.html#scenario-product-launch)
- [View scenario roles in the market](https://harzva.github.io/awesome-bot/?lang=en&scenario=product-launch)

### Accept one scenario result

1. Prepare the minimum materials listed in the scenario, starting with sanitized samples.
2. Give the first task to its role and check scenario acceptance criteria.
3. Resolve gaps and pass outputs, sources, and unknowns with a handoff card to the next owner.
4. Save final outputs and failure causes. A scenario download does not execute the workflow.

### Sources

Sources checked: 2026-10-25

- [Scenario source data](https://github.com/Harzva/awesome-bot/tree/main/data/scenarios)
- [Scenario first-use guide](https://github.com/Harzva/awesome-bot/blob/main/START_HERE.en.md)

## Let an Agent read the role it needs

Read a small index and one role, checking version, language, and SHA-256.

### Start with a small index

Team readers can focus on discovering roles as needed, supplying context and confirming permissions. Collaboration does not require cloning the repository, installing Node or having every collaborator calculate SHA-256 manually. Continue to “Reading and trust boundaries”; the local snapshot lab can be left to developers.

1. Read llms.txt and choose the zh or en index.
2. Choose one ID for the task, then read its JSON or Markdown.
3. Explain inputs, outputs, prerequisites, and needs, then work under the Agent's own rules.

- [Reading guide](https://harzva.github.io/awesome-bot/llms.txt)
- [Chinese index](https://harzva.github.io/awesome-bot/agents/zh/index.json)
- [English index](https://harzva.github.io/awesome-bot/agents/en/index.json)
- [Reading and trust boundaries](https://harzva.github.io/awesome-bot/handbook-agents.en.html#trust)

### Four machine-readable formats

| schema | Actual purpose |
| --- | --- |
| openbot.market.registry/1 | Discover versions, manifest URLs, and integrity hashes |
| openbot.market/1 | Canonical role manifest: persona, skills, and declared needs |
| openbot.fleet/1 | Configuration for host preview and confirmation |
| awesome.bot.agent/1 | Localized role context, provenance, and configuration fields |

id, templateVersion, locale, and contentRevision identify context. configuration.bytes and configuration.sha256 identify download bytes. Localized projections can differ from canonical manifests; do not check an English Fleet against a Chinese manifest digest.

The following excerpt shows fields from the existing Status Report Writer Agent card; it is not a complete importable file. Declared manifest needs are not granted permissions. Check actual settings in the Fleet export and host confirmation.

```json
{
  "schema": "awesome.bot.agent/1",
  "id": "awesome/status-report-writer",
  "templateVersion": "1.0.0",
  "locale": "en"
}
```

### Read and verify SHA-256

This Node.js 22+ example only reads and verifies; it does not import or execute configuration. Stop on a mismatch and retrieve a consistent version or a release snapshot with checksums.

```js
import assert from 'node:assert/strict';
import { createHash } from 'node:crypto';
const base = 'https://harzva.github.io/awesome-bot/';
async function read(url) {
  const r = await fetch(url, { signal: AbortSignal.timeout(10000) });
  assert.equal(r.status, 200);
  return r;
}
const card = await (await read(base + 'agents/en/status-report-writer.json')).json();
assert.equal(card.schema, 'awesome.bot.agent/1');
assert.equal(card.id, 'awesome/status-report-writer');
assert.equal(card.locale, 'en');
const bytes = Buffer.from(await (await read(card.configuration.url)).arrayBuffer());
assert.equal(bytes.length, card.configuration.bytes);
assert.equal(createHash('sha256').update(bytes).digest('hex'), card.configuration.sha256);
console.log(card.id, card.templateVersion, card.locale, card.contentRevision);
```

### Reading and trust boundaries

Copy for Agent copies a prompt; the site does not contact an Agent. If links are inaccessible, provide the relevant Markdown through normal paste or attachment and state the limitation. A SHA-256 match proves agreement with metadata, not publisher identity. The current catalogue is unsigned.

After understanding these boundaries, team readers can continue to troubleshooting. Actual integration, download and upgrade work must still perform the integrity and trust checks required by the applicable contract, through the responsible integrator or tools.

- [Team path: continue to troubleshooting](https://harzva.github.io/awesome-bot/handbook-troubleshooting.en.html?path=team)

### Verify a local snapshot and reject an altered copy

Use Node.js 22+, clone this repository from GitHub, and enter its root before running the setup below. Cloning, dependency installation, and building may need network access. Only the verification phase below reads entirely local files. It does not call a model or establish offline model execution. The commands use a macOS/Linux or Windows WSL shell. In another terminal, save the code between the JS markers as an .mjs file and run it with Node.

```sh
git clone https://github.com/Harzva/awesome-bot.git
cd awesome-bot
npm ci --ignore-scripts
npm run check
npm run build:site
```

If the repository is already cloned and npm ci --ignore-scripts has completed, start at npm run check. Repair a failed check or retrieve a complete consistent source snapshot before proceeding. Copy and run the entire sh block below from the repository root. It reads discovery, the English index, the Status Report Writer card, and then Fleet bytes. URLs must match the expected site and paths; local paths and symlinks must stay inside dist/site.

```sh
node --input-type=module <<'JS'
import assert from 'node:assert/strict';
import { readFile, realpath } from 'node:fs/promises';
import { resolve, sep } from 'node:path';
import { createHash } from 'node:crypto';
const root = await realpath(resolve('dist/site'));
const base = new URL('https://harzva.github.io/awesome-bot/');
async function bytesAt(url, expected) {
  assert.equal(url, new URL(expected, base).href, 'unexpected URL');
  const u = new URL(url);
  assert.equal(u.origin, base.origin);
  assert.equal(u.search + u.hash, '');
  assert.ok(u.pathname.startsWith(base.pathname));
  const relative = decodeURIComponent(u.pathname.slice(base.pathname.length));
  assert.ok(!relative.includes('\\') && !relative.includes('\0'));
  const path = resolve(root, relative);
  assert.ok(path.startsWith(root + sep), 'path escaped site root');
  const actual = await realpath(path);
  assert.ok(actual.startsWith(root + sep), 'symlink escaped site root');
  return readFile(actual);
}
async function jsonAt(url, expected) {
  return JSON.parse((await bytesAt(url, expected)).toString('utf8'));
}
const discovery = await jsonAt(new URL('agents/index.json', base).href, 'agents/index.json');
assert.equal(discovery.schema, 'awesome.bot.agent-discovery/1');
assert.equal(discovery.configurationFormat, 'openbot.fleet/1');
assert.ok(discovery.contentRevision);
const languages = discovery.languages.filter(x => x.locale === 'en');
assert.equal(languages.length, 1);
const index = await jsonAt(languages[0].url, 'agents/en/index.json');
assert.equal(index.schema, 'awesome.bot.agent-index/1');
assert.equal(index.locale, 'en');
assert.equal(index.contentRevision, discovery.contentRevision);
assert.equal(index.count, index.entries.length);
assert.equal(languages[0].count, index.count);
const matches = index.entries.filter(x => x.id === 'awesome/status-report-writer');
assert.equal(matches.length, 1);
const entry = matches[0];
const card = await jsonAt(entry.json, 'agents/en/status-report-writer.json');
assert.equal(card.schema, 'awesome.bot.agent/1');
assert.equal(card.id, entry.id);
assert.equal(card.locale, index.locale);
assert.equal(card.contentRevision, index.contentRevision);
assert.ok(entry.templateVersion);
assert.equal(card.templateVersion, entry.templateVersion);
assert.equal(card.configuration.format, 'openbot.fleet/1');
assert.equal(card.configuration.locale, card.locale);
assert.equal(card.configuration.grantsTools, false);
assert.equal(card.configuration.grantsContainer, false);
assert.equal(card.configuration.includesAccountsOrMemory, false);
assert.equal(card.configuration.importRequiresHostConfirmation, true);
const original = await bytesAt(card.configuration.url, 'exports/en/status-report-writer.fleet.json');
function verify(bytes) {
  assert.equal(bytes.length, card.configuration.bytes, 'byte length mismatch');
  assert.match(card.configuration.sha256, /^[0-9a-f]{64}$/);
  assert.equal(createHash('sha256').update(bytes).digest('hex'), card.configuration.sha256, 'SHA-256 mismatch');
}
verify(original);
const fleet = JSON.parse(original.toString('utf8'));
assert.equal(fleet.schema, card.configuration.format);
assert.equal(fleet.mode, 'config');
assert.equal(fleet.bots.length, 1);
const bot = fleet.bots[0];
assert.equal(bot.id, card.id.split('/')[1]);
assert.equal(bot.toolsEnabled, false);
assert.equal(bot.containerEnabled, false);
assert.deepEqual(bot.messages, []);
assert.deepEqual(bot.files, []);
assert.deepEqual(bot.channels, {});
assert.deepEqual(bot.memory, { profile: '', journal: [] });
assert.equal(bot.summary, null);
assert.deepEqual(fleet.shared, { skills: [], files: [] });
console.log('PASS original snapshot');
const altered = Buffer.from(original);
assert.ok(altered.length > 0);
altered[0] ^= 1;
assert.throws(() => verify(altered), { code: 'ERR_ASSERTION', message: /SHA-256 mismatch/ });
verify(original);
console.log('PASS altered copy rejected');
JS
```

Completion requires the two lines PASS original snapshot and PASS altered copy rejected, in that order, with exit code 0. Versions and digests come from the current snapshot; no hard-coded version or SHA is needed. The negative case flips one byte only in a Buffer copy and uses assert.throws to prove rejection. Source files and original artifacts are never written.

Each layer is checked against its actual schema. ID and templateVersion agree between index and card; locale agrees across index, card, and configuration; contentRevision agrees across discovery, index, and card. Fleet has no locale, templateVersion, or contentRevision fields. Its schema, single Bot slug ID, and actual empty structures are checked without inventing fields.

- ENOENT: confirm the repository-root working directory, Node.js 22+, and successful npm run check and npm run build:site. Do not fill missing files manually from another version.
- Version, language, or URL assertion failure: stop using the mixed snapshot and regenerate all of dist/site from one Git snapshot before retrying. Do not relax assertions.
- Byte-length or SHA-256 failure: keep the failure record and regenerate or retrieve a complete consistent snapshot. Do not edit the card digest to accept a bad file.

### Distinguish the two digests

| Field | Input and format | Comparison boundary |
| --- | --- | --- |
| registry integrity | canonicalJson of the canonical manifest: recursively sorted keys and no formatting whitespace; SHA-256 encoded as sha256-\<base64\>. | Defined by integrityOf in engine/src/manifest.mjs; it is not a digest of raw download bytes. |
| Agent configuration.sha256 / bytes | The exact Fleet export bytes at configuration.url; SHA-256 is 64 hexadecimal characters and bytes is the byte count. | Computed from the artifact by scripts/agent-surface.mjs; compare only bytes from the same URL, language, and snapshot. |

The CLI wrapper scripts/market.mjs reuses engine export, which defaults to Date.now(); site builds use the fixed metadata.updatedAt time. exportedAt and Bot createdAt can therefore differ. The Chinese canonical projection and English site projection also differ in persona and other text. Even with the same role ID and template version, export bytes and digests can differ. Do not interchange registry integrity, a CLI file digest, or Chinese and English download digests.

### Sources

Sources checked: 2026-10-25

- [Agent reading and verification](https://github.com/Harzva/awesome-bot/blob/main/docs/agent-integration.md)
- [Format contract](https://github.com/Harzva/awesome-bot/blob/main/INTEGRATION.md)

## Contribute, build, and publish

Edit declarative source entries and keep downloads, indexes, and pages consistent.

### Edit the correct source file

Each entry has one JSON file in data/entries/. Choose bot-role or task-workflow and describe mission, inputs, outputs, steps, prerequisites, sources, and license. Exclude scripts, credentials, conversations, and private memory.

| Source field | Meaning | Check |
| --- | --- | --- |
| id / version | Stable identity and template version | Preserve published version bytes |
| collection | bot-role or task-workflow | Classify by responsibility or output |
| inputs / outputs / workflow | Materials, outputs, and steps | Can a checkable first task be written? |
| requirements / references / license | Prerequisites, sources, and license | Avoid unsupported capabilities or official status |

### The CLI plans or exports

scripts/market.mjs supports help, list, info, plan, and install. install generates a file and requires --out and a target host version; it does not install into a running App. Users explicitly choose whether to accept community content and an unpinned trust source.

```sh
npm run market -- help
npm run market -- list --query=research
npm run market -- info awesome/grok-researchy
# Replace 0.9.9 with the actual target host version.
npm run market -- plan awesome/grok-researchy --openbot=0.9.9 --allow-community --allow-unpinned
npm run market -- install awesome/grok-researchy --openbot=0.9.9 --allow-community --allow-unpinned --out=./researchy.fleet.json
```

The standalone CLI exposes no upgrade or rollback patches. Fleet imports can rename IDs; host reconciliation of actual Bot IDs must precede upgrades that preserve user edits.

### Check generated bilingual output

1. Use Node.js 22+, read the contribution guide, then edit a declarative entry.
2. Maintain complete English content; Chinese fallback is not a translation.
3. Generate and check, then inspect generated diffs and individual downloads.
4. Stage only intended public files before the public-content audit.

```sh
npm ci --ignore-scripts
npm run build
npm run check
npm run check:versions
npm test
npm run build:site
npm run audit:public
```

### Publish immutable versions

Published template versions and release assets are immutable. Correct instructions in a new version while retaining licenses and historical digests. CI checks the catalogue, exports, and site. The Pages workflow builds the static site, and version tags must match package.json. A workflow file does not prove deployment; check deployment results and pages afterward.

```sh
npm run pack:release
# From the release download directory on macOS:
shasum -a 256 -c SHA256SUMS
```

- [Contribution guide](https://github.com/Harzva/awesome-bot/blob/main/CONTRIBUTING.md)
- [Publishing details](https://github.com/Harzva/awesome-bot/blob/main/docs/publishing.md)

### Understand CLI output and failures

--json selects the command result format; trust checks can still write warnings to stdout. Invoking npm run market may add npm script banners. Do not JSON.parse the entire stdout or assume a dedicated flag removes all diagnostic output. For file export, use --out=\<file\>, then read and parse that file after command success. Keep the exit code and diagnostic output.

install generates a Fleet configuration file; it does not write a Bot into the running App. This wrapper requires an explicit target --openbot and does not detect the running host version. npm run market -- help shows usage and a 0.9.9 example, not the current host or default planning version. Before retrying, verify the actual version using the target host’s own version information. If it is unknown, stop compatibility planning rather than guess 0.9.9 or a default. Acceptance of community content and an unpinned source is an explicit user choice; repairing a parameter error must not silently add acceptance flags.

| Failure or symptom | Meaning and recovery |
| --- | --- |
| plan / install missing --openbot | The error starts with Provide --openbot=\<target-version\>. This wrapper requires the actual target version and does not detect the running host. Check the target host’s own version information, then retry with --openbot=\<target-version\>. If unknown, stop compatibility planning; do not copy the help example or guess a default. |
| install missing --out | The error is Provide --out=\<file\>; this command generates a configuration file and does not install into your App. Choose a writable new destination file, add --out=\<file\>, and retain the correct --openbot. If both are missing, the --out error comes first. |
| --out= or --out without a path | The error is --out requires a file path. Supply a nonempty file path; a bare flag does not select a destination automatically. |
| Warnings or banners precede JSON on stdout | Mixed output does not imply a corrupted Fleet file. Check the exit code and read warnings. Read exported data from the --out file; inspect wrapper help with npm run market -- help. |

### Sources

Sources checked: 2026-10-25

- [Contribution guide](https://github.com/Harzva/awesome-bot/blob/main/CONTRIBUTING.md)
- [Actual CLI wrapper](https://github.com/Harzva/awesome-bot/blob/main/scripts/market.mjs)
- [CI and publishing rules](https://github.com/Harzva/awesome-bot/blob/main/docs/publishing.md)
- [Complete entry example](https://github.com/Harzva/awesome-bot/blob/main/data/entries/status-report-writer.json)

## Locate the failing layer first

Preserve materials and error evidence, then choose low-risk reversible checks.

### Quick troubleshooting table

| Symptom | Check first | Next step |
| --- | --- | --- |
| Site fails to load | Network and catalogue load status | Retry the same filters or read the GitHub catalogue |
| No Bot after download | Whether only a download occurred | Use the current host import preview and confirmation |
| Collection cannot import | Whether a file exceeds 200 Bots | Choose one role or release parts and check host total limits |
| Cannot read mail or files | Tools, account authorization, and readable materials | Provide sanitized materials or obtain required task access |
| English instructions in Chinese mode | Whether it is an attributed adaptation | Read adaptation notes and specify output language |
| SHA-256 mismatch | Whether card and download share a publication | Stop import and retrieve a consistent version or release snapshot |
| Complete-looking output lacks evidence | Whether sources and criteria are present | Add materials and list unknowns and conflicts |

If a file cannot be read, paste these two lines of public fictional text directly into the current Agent. Ask it to restate only the two facts with line numbers. Do not include customer materials.

```text
1 | Fictional project: Paper Plane; draft due Friday.
2 | Desktop tests passed; mobile tests not started.
```

If the restatement is correct, record “pasted text readable; original file reading still unverified” and save the result. Next check only the original file path, format, or access. If text also fails, preserve the error to investigate the model or session. Avoid blind retries under unchanged conditions and retain successful steps.

### Submit reproducible feedback

```text
Public feedback (sanitize first)
Page or public Bot ID:
Template version / language / content revision:
Host version (for import issues):
Time and minimal steps:
Expected result:
Actual result and error code:
Small public sample:
Sensitive-material handling status (if applicable; no sensitive values):
Exclude accounts, keys, private conversations, and customer materials.
```

Role detail feedback links prefill the public Bot ID, template version, and source. Review your additions before submission and keep complete private logs out of public feedback.

If sensitive material was pasted by mistake, address the exposure first: revoke or rotate credentials at the relevant service; deleting a chat does not invalidate credentials. For customer materials, delete them or restrict access in the actual service and establish the exposure scope. Report only handling status and necessary scope details, without repeating sensitive values.

### Preserve work before recovery

1. Save drafts, downloads, and necessary sanitized error details.
2. Separate site, format, host-import, model, and account problems.
3. Retry reading or reproduce with a small sample before considering a reset.
4. Follow current host documentation for running instances and record actual results.

### Three common misunderstandings

| Question | Answer |
| --- | --- |
| Does opening a source link install a Bot? | No. Original-site conditions and actions apply separately. |
| Does a working role certify account tasks? | No. Format checks differ from real-account acceptance. |
| Do Bots automatically share private memory? | Configurations do not transfer memory; hand off explicitly authorized packets. |

- [Public issue tracker](https://github.com/Harzva/awesome-bot/issues)

### Sources

Sources checked: 2026-10-25

- [Site and feedback notes](https://github.com/Harzva/awesome-bot/blob/main/README.md)
- [Import and verification scope](https://github.com/Harzva/awesome-bot/blob/main/INTEGRATION.md)
- [Digest mismatch handling](https://github.com/Harzva/awesome-bot/blob/main/docs/agent-integration.md)

## Terms, licenses, and sources

Look up fields and provenance, distinguishing originals, English adaptations, and external references.

### Glossary

| Term | Meaning in this handbook |
| --- | --- |
| Agent | An executor that uses a model, instructions, and available tools in a host to handle tasks; its capabilities depend on actual configuration and authorization |
| Bot role | Configuration of responsibilities, methods, and prerequisites |
| Host | The application or runtime that runs a Bot or Agent and manages available tools and account authorization |
| Model | The component providing generation and reasoning; available tools and account permissions are configured separately in the host |
| Task workflow | Steps organized around a specific output |
| Fleet | Configuration file for host import review |
| Canonical manifest | Role manifest preserving published version bytes |
| Localized projection | Localized content and download of the same source role |
| Configuration digest | SHA-256 identifying exact download bytes |
| Trust anchor | Independently pinned publisher-verification basis, not bundled here |
| Acceptance | Checking a task output against explicit criteria |

### Find licenses and attribution

The 315 roles include 223 source-adapted roles; there are also 56 task workflows. Shared Bots are source links and are excluded from this site’s importable configuration count. For each entry, check license / references in data/entries and the applicable license files.

Original site content and code use MIT. Among 223 attributed roles, mergisi/awesome-grokbot uses CC0-1.0; cobusgreyling/grok-bot-templates and PramodDutta/botskills use MIT. Adaptations retain original instructions, provenance, digests, and applicable notices. Upstream names and brands remain their owners' property.

1. Read author, source URL, and template version in details.
2. Before redistribution, read applicable licenses and third-party notices and retain required attribution.
3. Check each external project's license; a reference link does not grant permission to copy software or assets.

- [Project license](https://github.com/Harzva/awesome-bot/blob/main/LICENSE)
- [Third-party notices](https://github.com/Harzva/awesome-bot/blob/main/THIRD_PARTY_NOTICES.md)
- [Adaptation source inventory](https://github.com/Harzva/awesome-bot/blob/main/data/imported-role-sources.json)

### Further reading

- [Market home](https://harzva.github.io/awesome-bot/?lang=en)
- [Handbook home](https://harzva.github.io/awesome-bot/handbook.en.html)
- [Shared Bots source directory](https://harzva.github.io/awesome-bot/shared-bots.html?lang=en)
- [Projects and references](https://harzva.github.io/awesome-bot/resources.en.html)
- [Machine-readable registry](https://harzva.github.io/awesome-bot/registry/index.json)
- [Releases and checksums](https://github.com/Harzva/awesome-bot/releases)

### How this handbook uses sources

This handbook learns from grokbot-guide's learning paths, scenario acceptance, and layered troubleshooting. Its text and exercises are original. Grok cloud computers, routines, app connections, and approval menus are platform-specific and are not presented as connected OpenBot capabilities. Feature facts rely on this repository's documentation and data contracts; account tasks still need separate acceptance.

- [Structural reference at a fixed revision](https://github.com/anightmonarch/grokbot-guide/tree/65688ac52e2a14b160393688bdfb2734ecc6dcc7)

### Sources

Sources checked: 2026-10-25

- [Site license](https://github.com/Harzva/awesome-bot/blob/main/LICENSE)
- [Third-party attribution and licenses](https://github.com/Harzva/awesome-bot/blob/main/THIRD_PARTY_NOTICES.md)
- [Adaptation and indexing boundaries](https://github.com/Harzva/awesome-bot/blob/main/docs/market-aggregation.md)
- [Learning-path structural reference](https://github.com/anightmonarch/grokbot-guide/tree/65688ac52e2a14b160393688bdfb2734ecc6dcc7)