Workflows

In brief: TestChimp Workflows are modular agent playbooks plus project policies—so teams get repeatable QA behaviour, auditability, and room to optimize with alternate policies.

Workflows are how agents (Claude Code, Cursor, and cloud agents) run QA with TestChimp: each workflow has a skill playbook (battle-tested steps) and an optional project policy (your team’s decisions). The platform Workflows catalog mirrors the skill so local and cloud runs stay aligned.

What workflows are

Kind	Examples	Role
Composite	Run QA, Upkeep	One approved plan that chains subflows end-to-end
Atomic	Implement Requirement, Create tests, Cleanup, …	Single job you invoke on its own or as a composite subflow
Meta	Create policy, Skill upgrade	Author policies and keep the skill current

Playbooks live in the TestChimp skill. Policies live in your repo under plans/knowledge/policies/*.policy.md and sync to TestChimp.

Why it matters

• Repeatable team behaviour — Policies capture env strategy, scoping, quality bars, and which composite steps to skip—so agents do not re-negotiate the same choices every PR.
• Auditability — Every mutative agent action can report the policy file + version and a stable workflow_execution_id, visible on the Workflows execution timeline.
• Optimization — Keep a default policy and try variants (--policy run-qa-smoke.policy.md) for smoke vs full, staging vs ephemeral, or stricter quality gates without forking the skill.
• Project and team overrides — Same playbooks, different policies per project (or alternate files for special runs).

Set up a local workspace

1. Project-local MCP — Add MCP config for @testchimp/cli under the project (for example Cursor: <project>/.cursor/mcp.json), with TESTCHIMP_API_KEY for that TestChimp project—not only a global user config.
2. Install the skill — Clone testchimp-skills into your agent skills directory (for example ~/.cursor/skills/testchimp or .cursor/skills/testchimp). Keep .git so you can git pull or run /testchimp skill upgrade.
3. Map Git folders — In TestChimp → Project settings → Integrations → Git, map plans and tests folders and sync markers (.testchimp-plans, .testchimp-tests). See Code repository overview.
4. Bootstrap — Run /testchimp init once to wire Playwright/reporter, fixtures, seeds, CI, default policies, and environment strategy.

The in-product Workflows list also walks through MCP + install + init for the current project.

Invoking workflows

Use a slash command or natural language. The skill routes to the matching playbook.

Examples:

/testchimp run QA
/testchimp test plans/stories/billing
/testchimp implement US-181
/testchimp upkeep
/testchimp evolve --policy upkeep-weekly.policy.md
/testchimp create tests for checkout
/testchimp connect to test environment

Synonyms (same catalog workflow):

You say	Catalog id
/testchimp test, /testchimp run QA	run-qa
/testchimp evolve, /testchimp upkeep, legacy audit	upkeep
/testchimp explore, /testchimp run explorechimp	run-explorechimp
/testchimp implement, /testchimp implement <story/scenario id>	implement

Prefer MCP tools when available; CLI is the fallback after the skill preamble.

Policies

A policy answers: how should this workflow run for us? Playbooks stay generic; policies hold project choices (scoping, env, subflow order, quality bar, exclusions).

Location: plans/knowledge/policies/*.policy.md

Required frontmatter:

---
workflow-id: run-qa
version: 1.0.0
---

Bump version whenever guidance changes so report-agent-action stays meaningful.

Resolution order:

1. Explicit --policy / POLICY_FILE
2. <workflow-id>.policy.md
3. Other *.policy.md with matching workflow-id
4. Fallback: decisions in plans/knowledge/ai-test-instructions.md

Init seeds default run-qa.policy.md and upkeep.policy.md when missing. connect-to-test-env requires its own policy (not auto-seeded)—many automation workflows stay Missing config until it exists.

Author or update policies with /testchimp create policy <workflow-id>, then upsert-policy so the platform has them immediately (git push also syncs later).

Policy use cases

• Team-specific overrides — Skip ExploreChimp in run-qa, pin staging URLs, forbid certain refactors while fixing flakes.
• Trying alternate policies — Smoke vs full composites, weekly upkeep with broader cleanup, staging-only connect policy via --policy ….
• Environment gate — Encode feature-branch / default-branch / CI connect rules so every dependent workflow reuses one source of truth.

Traceability

For Plan → approve → Execute runs:

1. During Plan, mint one ULID as workflow_execution_id and keep it for the whole run.
2. After mutative actions, call report-agent-action with workflow_id, workflow_execution_id, policy_file / policy_version, git_sha, actor, branch, and entity identity.
3. End with ACTION_COMPLETED or ACTION_FAILED.

The Workflows UI shows policy file + version on the execution timeline. That is how you compare runs when optimizing policies or debugging unexpected agent behaviour.

Scope when unspecified

Applies to all optional-scope workflows (composites share one scope for the whole run):

1. Explicit scope in the prompt → use it.
2. Else feature / PR branch → changes vs merge base / default branch.
3. Else default branch → changes since the last run of that workflow (get-last-run-workflow-detail); if missing or ambiguous → ask for a history window.

Policy ### Scoping Rules may narrow scope, not contradict this rule.

Requires explicit identity (no auto-scope): requirement quality checks, fix test execution, fix issue, run release check, create policy (needs a workflow id).

Platform scope (web / iOS / Android) is deduced separately when multi-platform; ask if ambiguous.

Catalog (by platform section)

Same sections and order as the in-product Workflows catalog (Composite → Requirement Planning → Development → Test Automation → …).

Composite

• Run QA — /testchimp run QA / test
• Upkeep — /testchimp upkeep / evolve

Requirement Planning

• Author plans
• Run requirement quality checks

Development

• Implement Requirement — /testchimp implement <story / scenario id>

Test Automation

• Create tests
• Run smart regression
• Fix test execution
• Fix coverage gaps
• Cleanup

Issue Management

• Fix issue

Non-functional testing

• Run ExploreChimp
• Run release check

TrueCoverage

• Instrument TrueCoverage

Test Environment Management

• Connect to test environment

Meta

• Create policy
• Skill upgrade

Supporting docs

• /testchimp init — Bootstrap infra and default policies
• TestChimp approach to test automation — Hybrid Playwright + agentic strategy
• Playwright runtime plugin — @testchimp/playwright reporter and AI steps