Dailybot Forms

Dailybot Forms

> Requires dailybot-cli >= 3.7.0 (the skill-pack baseline). The full forms lifecycle — form list / submit / get / responses / response get / update / transition / delete — plus the structured --json 4xx error shape are all available. If dailybot --version is below 3.7.0, ask the developer to run dailybot upgrade. See [../SKILL.md § Required Dailybot CLI version](../SKILL.md#required-dailybot-cli-version) for install commands and version-check tooling.

You help developers work with the full Dailybot forms lifecycle: list, inspect, submit, update, transition between workflow states, and read prior responses. Forms are custom questionnaires created by team leads — feedback surveys, retrospectives, release checklists, approval flows, or any structured data collection. Some forms are simple "fill once and done"; others have workflow states (e.g. draft → review → released) with audience-scoped permissions on who can edit and who can transition.

This skill is distinct from daily check-ins (handled by dailybot-checkin) and free-text reports (handled by dailybot-report).

---

Upgrade-safety contract — read this before editing forms behavior

This SKILL.md is the universal forms skill. It is overwritten on every upgrade of the Dailybot skill pack (managed by skills-lock.json). Two rules keep customer customizations safe:

| MUST | MUST NOT | |------|----------| | Read .dailybot/profile.json and honor vars.custom_form_skills. | Write anything outside .agents/skills/dailybot/. | | Defer to a custom skill when the resolver finds a mapping. | Read, modify, or scan files under .agents/skills/dailybot-custom/ or any other customer-owned namespace. | | Warn (do not error) when a registered custom-skill path is missing on disk — fall back to the generic flow. | Send .dailybot/profile.json contents (especially vars) in any report / payload to the server. | | Document this contract verbatim here. | Embed customer-specific logic in this universal skill — if you find yourself writing if form.name == "Release Form":, the right answer is a custom skill under .agents/skills/dailybot-custom/. |

Customer-authored form skills live at .agents/skills/dailybot-custom//SKILL.md. The universal skill MUST defer to them; never copy customer logic into this file.

---

Auth model — API key or login

All form commands accept either a Bearer login session (dailybot login) or an org API key (DAILYBOT_API_KEY). Access is scoped to the acting identity's permissions (the server resolves the API key's owner) — they only see forms (and responses) they have access to, and the server enforces every audience check on the API side.

If the developer has only an API key, form commands still work — the CLI falls back to X-API-KEY.

---

When to Use

• The developer asks "what forms do I have?", "list my forms", "show available surveys"
• The developer asks to "fill out the retro form", "submit the feedback survey", "answer the pulse check"
• The developer wants to continue an in-progress form response: "keep filling the release form", "update my draft"
• The developer wants to move a response forward: "mark the release as approved", "transition to released", "send for review"
• The developer wants to read prior responses: "show me the last release form", "what was answered last time?"
• The developer wants to delete a response they own

Do not use this skill for daily standup check-ins — route those to dailybot-checkin. Forms are ad-hoc, periodic, or workflow-driven; check-ins are recurring daily/weekly rituals tied to follow-ups.

---

Step 1 — Verify Setup

Read and follow the authentication steps in [../shared/auth.md](../shared/auth.md). That file covers CLI installation, login, API key setup, and agent profile configuration.

Additionally, confirm at least one credential is present (a login session or an API key):

dailybot status --auth 2>&1

If the output shows a logged-in user session or a configured API key, proceed. Otherwise guide them through dailybot login (see auth.md) or ask them to set DAILYBOT_API_KEY.

A scripted preflight that does both at once and exits with code 3 if unauthenticated:

dailybot status --auth >/dev/null 2>&1 || { echo "Run: dailybot login"; exit 3; }

If auth fails or the developer declines, skip and continue with your primary task.

---

Step 2 — Lifecycle Decision Tree

When the developer asks anything form-related, walk this tree before acting:

1. Identify the target form by name or slug (or pick from a list).
2. Run `dailybot form list --json` to find its UUID and confirm visibility.
3. Run `dailybot form get  --json` to read questions, the `workflow`
   object (`null` or `{enabled, states}`), audience configuration, and the form's slug.
4. RESOLVER: check .dailybot/profile.json → vars.custom_form_skills.
   - If a custom skill is registered for this form (by UUID or by slug),
     LOAD THAT SKILL'S SKILL.md and follow its instructions INSTEAD of
     continuing the generic flow.
   - Otherwise, continue.
5. Decide whether to continue an existing response or start fresh:
   - `dailybot form responses  --latest --json`
   - If a response exists and its `current_state` is NOT terminal
     (or the form allows reopening), prefer the update + transition path.
   - Otherwise, submit a new response.
6. After every mutating call, re-read `current_state` and `allowed_transitions`
   on the response to decide the next move (update? transition? done?).

The resolver step (4) is the customer-extension hook. See Step 7 — Custom-skill resolver below.

---

Step 3 — List Available Forms

dailybot form list --json

Returns all forms in the caller's organization. Every org member sees every org form; capabilities (editing, response visibility, state changes) are governed by each form's permissions. Pass --mine to narrow to only your own forms. (If a developer reports "I only see a handful of my forms," check dailybot --version and have them dailybot upgrade — older CLIs had a server-side visibility bug.) The shape is stable and machine-readable:

[
  {
    "uuid": "",
    "slug": "team-feedback",
    "name": "Team Feedback",
    "workflow": null,
    "questions": [
      {
        "uuid": "",
        "question": "How was your week?",
        "question_type": "text_field"
      }
    ]
  },
  {
    "uuid": "",
    "slug": "code-release-form",
    "name": "Code Release Form",
    "workflow": { "enabled": true, "states": [ ... ] },
    "questions": [ ... ]
  }
]

> The slug field is stable across environments (dev / staging / prod), while id rotates per environment. Prefer slug for any persistent mapping you keep across deployments. See the resolver in Step 7.

Pagination, search, and date filters

> Note: the shared list query flags below are part of the dailybot-cli >= 3.7.0 baseline. Older CLIs > return the full list with no filtering.

form list accepts the full shared list query flag set — pagination (--page, --page-size, --all, --limit), search (--search / --grep), and date range (--since, --until, --date, --last-week, --today). With no flags it fetches everything. The complete flag table, the {count, next, previous, results} envelope, and the Showing X of N footer are documented once in [../shared/list-query-and-errors.md](../shared/list-query-and-errors.md).

# Search forms by name, restricted to a date range:
dailybot form list --search retro --since 2026-07-01 --json

# Fetch every page explicitly (equivalent to the no-flag default):
dailybot form list --all --json

# One explicit page of 20:
dailybot form list --page 2 --page-size 20 --json

Filter by owner — --mine and --owner

Pass --mine to narrow the result to only the forms you own, or --owner (repeatable) to filter by specific owners. --owner accepts a UUID, email, or name — non-UUID values are resolved via the org directory. The two flags can be combined (AND semantics with every other filter).

# Only the forms I own:
dailybot form list --mine --json

# Forms owned by a specific person (by name):
dailybot form list --owner "Jane Doe" --json

# Forms owned by two people (by UUID):
dailybot form list --owner  --owner  --json

> Deprecation: the --filter me scope is deprecated server-side. Use > --mine or --owner instead — --filter me still works but maps to > the legacy filter=me parameter.

Form owners picker — form owners

A lightweight endpoint to discover which org members own at least one form, without pulling the full member directory.

dailybot form owners                     # table of owners
dailybot form owners --search jane       # search by name/email
dailybot form owners --json              # machine-readable

Each result has uuid, full_name, image, role, and optionally email (email is only visible to admins/managers — the CLI must not assume it exists).

Server-side filtering, sorting, and archived forms

| Flag | Values | Description | |------|--------|-------------| | --filter | all, public, approval, workflow, archived | Scope filter (server-side). me still works but is deprecated. | | --owner | UUID, email, or name (repeatable) | Filter by form owner(s). Max 50. | | --order | alphabetical, recent, total | Sort field (total = total response count). | | --ascending / --asc | flag | Sort ascending (default: descending). | | --include-questions | flag | Include question definitions in each form. | | --include-archived | flag | Include archived forms (hidden by default). |

# Workflow-enabled forms, sorted alphabetically ascending:
dailybot form list --filter workflow --order alphabetical --asc --json

# Only forms with approval flow:
dailybot form list --filter approval --json

# Public forms sorted by total responses:
dailybot form list --filter public --order total --json

# Archived forms:
dailybot form list --filter archived --json

# Include question definitions:
dailybot form list --include-questions --json

> The envelope is unconditional. GET /v1/forms/ and the responses endpoint > below always return {count, next, previous, results}; no query parameter is > needed. See the shared doc.

Present forms to the developer

When forms are found:

> "You have 2 forms available in Dailybot: > > 1. Team Feedback — 3 questions (no workflow) > 2. Code Release Form — 8 questions (workflow: draft → review → released) > > Which one would you like to work with?"

When no forms are found:

> "No forms are available for you right now."

---

Step 4 — Inspect a Form

dailybot form get  --json

Use this before submitting or updating. It returns the form's full configuration including workflow definition and the audience-based permission flags. Treat this output as the source of truth for "what can I do on this form?".

JSON shape (workflow-enabled form)

The workflow definition is nested under the workflow key: null when the form has no workflow, or {"enabled": true, "states": [...]} when it does. Each state carries {key, label, color, order} — the ordered list defines the forward progression (the first state is the initial one, the last is the final/terminal one). allow_reopen_from_final_state is a top-level boolean. Audience permissions also live at the top level. All of it is server-defined.

{
  "uuid": "",
  "slug": "code-release-form",
  "name": "Code Release Form",
  "allow_reopen_from_final_state": false,
  "state_change_permission": { "audience": "...", "...": "..." },
  "edit_permission":         { "audience": "...", "...": "..." },
  "view_reports_permission": { "audience": "...", "...": "..." },
  "workflow": {
    "enabled": true,
    "states": [
      {"key": "draft",    "label": "Draft",    "color": "#9CA3AF", "order": 0},
      {"key": "review",   "label": "Review",   "color": "#F59E0B", "order": 1},
      {"key": "released", "label": "Released", "color": "#10B981", "order": 2}
    ]
  },
  "questions": [ ... ]
}

> A form with no workflow returns "workflow": null. The legacy workflow_enabled > boolean and workflow_config object are gone — read workflow and, when present, > workflow.enabled / workflow.states. The per-response moves the current caller can make > still arrive as allowed_transitions on each response payload (Steps 5–6) — the server > computes those from the ordered states and the caller's audience.

Audience permissions

The three *_permission fields are server-evaluated. Treat them as opaque in this skill — never re-implement the audience evaluation client-side. The server returns can_change_state, can_edit, and can_view_reports (or equivalent) on each response payload as the decided result. Trust those booleans.

---

Step 5 — Workflow-state Vocabulary

When the form has a workflow (workflow.enabled: true), the agent must understand five fields that appear on every response payload. Surface them when they affect what the developer can do next:

| Field | Meaning | Agent behavior | |-------|---------|----------------| | current_state | The effective state of this response right now. | Display the label. Drive the next action from it. | | allowed_transitions | [{to_state, label}] — the moves the current caller can make from current_state. Server-computed; honors audience. | Pick one and confirm with the developer before invoking transition. If the list is empty, no transitions are available to the caller. | | can_change_state | Boolean — whether the caller is in the audience for state changes. | If false, do not offer the transition path. Tell the developer the audience excludes them. | | allow_reopen_from_final_state | Form-level boolean. false (default) means the terminal state is sticky — once reached, the response cannot move out. | If false and current_state is a final state, do not attempt a transition. If true, the response can transition back to a non-final state. | | state_history | Append-only list of {from_state, to_state, actor_name, at} entries. | Surface the latest entry (who moved it last, when) when relevant for context. |

> Never infer state transitions from labels or names — the only valid moves are the ones in allowed_transitions. The server's audience checks may legitimately exclude transitions the developer thinks should be available.

---

Step 5.5 — Authoring forms (create / configure / questions)

> Requires dailybot-cli >= 3.7.0 (the skill-pack baseline). The full authoring surface — form create, form config (workflow states, the three permission audiences, anonymous/public/brand/require-identity with public_url, approval + approvers, the ChatOps command), form archive, the form questions add|edit|delete|reorder group, resolving people by email, --no-approvers, the 3 report-channel cap, and the create requires ≥ 1 question rule (questions_required) — is all available. If dailybot --version is below 3.7.0, ask the developer to run dailybot upgrade.

Everything above this point reads and responds to forms. This section builds and reshapes them. An agent with the right permissions can now create a form, wire up its workflow states, permission audiences, approval flow, and ChatOps command, and manage its questions — all end-to-end from the CLI, without opening the Dailybot webapp.

Permissions are server-enforced. Creating and configuring forms typically requires org admin / manager rights (or an API key whose owner has them). If the acting identity lacks the rights, the server returns a 403 — surface it and fall back to the non-blocking rule; never re-implement the permission check client-side.

On

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: DailybotHQ
• Source: DailybotHQ/agent-skill
• License: MIT

Install and usage instructions live in the source repository linked above.