Build a Software Development Team

This skill sets up a complete AI-powered software development team inside your OpenClaw instance. It covers two layers:

1. Agent setup — creating and configuring each agent (models, skills, routing, workspace files)
2. Project setup — creating the project folder structure that coordinates agents across sprints

Both layers are required for a fully working team. Use the table of contents below to jump to the relevant section.

Contents

• Credential and Security Model
• Heartbeat Scheduling
• Agent Workspace Files
• Before You Start
• Step 0 — Safety First
• Step 1 — Gather Project Information
• Step 2 — Model Selection
• Step 3 — Skills Selection Per Agent
• Step 4 — Agent Configuration
• Step 5 — Asana Project Setup
• Step 6 — Write Agent Workspace Files
• Step 7 — Create Project Folder Structure
• Step 8 — Credential Verification
• Step 9 — Enable Chat Completions
• Step 10 — Smoke Test
• Step 11 — Post-Setup Snapshot
• Step 12 — Handoff Summary
• Project Workflow Reference
• Sprint Management
• If Anything Goes Wrong

Reference files (read when needed):

• references/project-files.md — Full specification of every project folder file, its format, and its content rules
• references/workflow.md — Complete agent workflow: all phases, escalation rules, queue formats, git conventions

Credential and Security Model

This skill does not read, store, request, or transmit any credentials or secret values.

All credential handling is performed by:

• The openclaw-administrator skill, which uses OpenClaw's own config management to wire agent settings
• The Asana dependency skill installed on each agent, which holds and uses the Asana PAT
• The Git dependency skill installed on each agent, which holds and uses the GitHub PAT
• The Email dependency skill installed on the PM agent, which holds and uses email credentials

This skill collects only the names of env vars (e.g., TA_ASANA_PAT) — never their values. Those env var names are passed to the dependency skills so they know which credential to pull from the agent runtime environment.

Credentials must be stored in your secret management system (Kubernetes ConfigMap/Secret, .env file, or equivalent) before setup begins.

Heartbeat Scheduling

The 30-minute agent heartbeats configured in this setup are scheduled and triggered by the OpenClaw platform, not by this skill. This skill instructs the openclaw-administrator skill to set the heartbeat interval in each agent's OpenClaw config. This skill does not self-invoke, set timers, or persist between sessions.

Agent Workspace Files

This setup process creates and populates the following operator-managed workspace files for each agent:

• USER.md — project list, Asana GIDs, repo URLs, team roster. No secret values.
• TOOLS.md — available dependency skills and env var name labels each one uses.
• HEARTBEAT.md — what to check on each heartbeat run. No secret values.
• AGENTS.md — role instructions including active project references and queue check rules.

These are plain text files in each agent's workspace directory. Created once during setup; updated by the operator when projects change.

Before You Start — Required Skills

Required (install before running this skill):

• openclaw-administrator (EncryptShawn) — performs all agent creation, model assignment, routing config, and workspace file writes.

Strongly recommended:

• openclaw-recovery-manager (EncryptShawn) — provides config snapshots and emergency rollback.

Step 0 — Safety First

Before touching any configuration:

1. Check if openclaw-recovery-manager is installed. If yes, take a snapshot:

   "Taking a pre-setup configuration snapshot before we begin." Label it: pre-dev-team-setup-[today's date]

2. If NOT installed, ask:

   "I recommend installing openclaw-recovery-manager (EncryptShawn on ClawHub) before we proceed. Want to install it first, or proceed without it?"

Step 1 — Gather Project Information

Ask the user for the following. Collect all answers before configuring anything:

I need a few details to set up the team correctly.

1. Project name?
   (e.g., talent_avatar — used as the project identifier throughout)

2. Asana workspace GID?
   (Found in your Asana workspace settings or URL)

3. Does an Asana project board already exist for this project?
   - Yes → What is the Asana project GID? (from the board URL)
   - No → I'll guide you through creating one

4. GitHub repository SSH URLs (private repos, SSH access only):
   - Frontend repo: (e.g., [email protected]:org/repo-fe.git)
   - Backend repo: (e.g., [email protected]:org/repo-be.git)
   - Any additional repos?

5. Credential env var names only — do not share token values here.
   What are the names of the env vars in your secret store for:
   - Asana PAT: (e.g., TA_ASANA_PAT)
   - GitHub PAT: (e.g., TA_GITHUB_PAT)
   - Dev Manager email address: (e.g., TA_DEV_MANAGER_EMAIL)

6. PM agent ID for this project?
   (Convention: project_manager_[project_name])
   Press enter to accept the suggested convention.

After collecting answers, confirm back with the user before doing anything.

Step 2 — Model Selection

Present model recommendations. Tell the user they can accept or change any agent's model.

Note: OpenRouter is strongly recommended for access to the full model range.

RECOMMENDED MODEL ASSIGNMENTS
Based on April 2026 SWE-bench Pro and AA-Omniscience hallucination data:

Agent          | Primary                  | Fallback         | Heartbeat       | Vision
---------------|--------------------------|------------------|-----------------|------------------
project_manager| GLM-5.1                  | MiniMax M2.7     | MiniMax M2.7    | —
               | $1.00/$3.20 per 1M       |                  | (cheap loop)    |
               | 34% H% — lowest of all   |                  |                 |
engineer       | Gemini 3.1 Pro           | Claude Opus 4.7  | Gemini 3.1 Pro  | Native (primary)
               | $2/$12 per 1M            | (escalation)     |                 |
dev-fe         | GLM-5.1                  | Qwen 3.6 Plus    | GLM-5.1         | Gemini 3.1 Pro
               | $1/$3.20 per 1M          |                  |                 | (mockup tasks)
dev-be         | GLM-5.1                  | Qwen 3.6 Plus    | GLM-5.1         | —
qa             | Gemini 3.1 Pro           | GPT-5.5          | Gemini 3.1 Pro  | Native (primary)
n8n_engineer   | GLM-5.1 (active)         | Qwen 3.6 Plus    | MiniMax M2.7    | —
               | MiniMax M2.7 (heartbeat) |                  |                 |

Why these picks:
- PM: GLM-5.1 has the lowest hallucination rate (34%) of all 10 frontier models.
  A PM that confidently misrepresents client or engineer statements is dangerous.
  MiniMax M2.7 (39% H%, $0.30/$1.20) is the cheap heartbeat/fallback model.
- Engineer + QA: Gemini 3.1 Pro has native vision — critical for reading mockups,
  rendered UI screenshots, and HTML/CSS visual diffs.
- FE Dev: GLM-5.1 is the default coding model, but switches to Gemini 3.1 Pro
  when a task involves a mockup. See "Vision Tasks" below.
- DeepSeek V4 Pro excluded despite strong benchmarks — 94% hallucination rate
  makes it unsuitable for any agent in this team.

Accept these recommendations? Or tell me which to change.

Vision Tasks (FE Dev and QA)

The FE dev and QA agent both need vision capability for tasks that involve visual references — mockups, design comps, rendered UI comparisons. Configure them so Gemini 3.1 Pro is used only when the task requires vision, not as the primary default (which would be more expensive than necessary for non-visual work).

Configuration approach (via openclaw-administrator):

• FE dev primary model: GLM-5.1
• FE dev vision model: Gemini 3.1 Pro
• QA primary model: Gemini 3.1 Pro (already vision-capable)
• QA fallback non-vision: GPT-5.5

The FE dev should switch to vision mode when the Asana task description references a mockup or attached image. The PROJECT.md instructs the FE dev to do this. QA should use vision mode whenever a PR includes UI changes that need to be compared against the mockup.

Mockup Storage

Mockups must be accessible to the engineer (during planning), FE dev (during implementation), and QA (during review). Two storage paths, in priority order:

1. Asana attachments (preferred) — if the Asana skill supports attachment upload/retrieval, mockups attach directly to the relevant Asana task. Each agent retrieves them via the Asana skill.
2. Project workspace fallback — ~/.openclaw/projects/[project_name]/workspace/mockups/
   • File naming: [task-id]-[short-description].[ext] (e.g. 1234-navbar-redesign.png)
   • The Asana task description must reference the filename so devs and QA can find it
   • This path is pre-created by this skill during Step 7

This mockup convention is documented in PROJECT.md so all agents know the rule.

Wait for confirmation. Record final selections.

Step 3 — Skills Selection Per Agent

Check what's already installed using the openclaw-administrator skill.

Dependency Skills (Required — Install First)

DEPENDENCY SKILLS — install these first on each agent:

All agents:
  - Asana skill (for Asana task management)

Agents that touch code (engineer, dev-fe, dev-be, qa, n8n_engineer):
  - Git skill (for repository operations)

PM agent only:
  - Email skill (for Dev Manager completion alerts)

Search ClawHub for the best-rated version of each if not already installed.

EncryptShawn Workflow Skills (All Agents)

- openclaw-administrator
- openclaw-recovery-manager
- approved-self-improver

Role-Specific Workflow Skills

project_manager_[project]: dev-project-manager (EncryptShawn)
engineer:                  dev-project-engineer (EncryptShawn)
dev-fe, dev-be, n8n:       project-dev (EncryptShawn)

Tech Stack Skills

Tech stack questions:

1. Frontend: Next.js / Nuxt / React / Vue / Astro / Flutter / other?
2. Backend: NestJS / Node.js / Python / Golang / other?
3. Database: MySQL / PostgreSQL / MongoDB / ClickHouse / Redis / other?
4. Using Directus as CMS or API layer? Yes / No
5. Using AWS Cognito for auth? Yes / No
6. Using N8N for automation? Yes / No
7. Using Qdrant for vector search? Yes / No

Based on answers, recommend and install appropriate ClawHub skills per agent.

Step 4 — Agent Configuration

Using the openclaw-administrator skill, configure each agent:

project_manager_[project]

• Model (active): GLM-5.1 (or user choice from Step 2)
• Model (heartbeat): MiniMax M2.7 (cheap heartbeat loop)
• Fallback: MiniMax M2.7
• Heartbeat: every 30 minutes, isolated session, light context
• Repos: read-only access to all repos
• Agent-to-agent allow list: engineer, dev-fe, dev-be, qa, n8n_engineer (if applicable)
• Chat completions: ENABLED

engineer

• Model (active): Gemini 3.1 Pro (native vision — required for mockup review)
• Fallback: Claude Opus 4.7 (escalation only)
• Heartbeat: Gemini 3.1 Pro
• Heartbeat: every 30 minutes
• Repos: read-only access to all repos (read/write only when explicitly helping a dev)
• Agent-to-agent allow list: [PM agent ID], dev-fe, dev-be, qa, n8n_engineer
• Chat completions: disabled

dev-fe

• Model (primary): GLM-5.1
• Model (vision): Gemini 3.1 Pro — used when task involves mockup/image references
• Fallback: Qwen 3.6 Plus
• Heartbeat: GLM-5.1
• Heartbeat: every 30 minutes
• Repos: frontend repo (read/write)
• Agent-to-agent allow list: [PM agent ID], engineer, qa
• Chat completions: disabled

dev-be

• Model (primary): GLM-5.1
• Fallback: Qwen 3.6 Plus
• Heartbeat: GLM-5.1
• Repos: backend repo (read/write)
• Agent-to-agent allow list: [PM agent ID], engineer, qa
• Chat completions: disabled

qa

• Model (primary): Gemini 3.1 Pro (native vision — required for UI/mockup comparison)
• Fallback (non-vision): GPT-5.5
• Heartbeat: Gemini 3.1 Pro
• Repos: all repos (read-only, plus merge authority on operator instruction)
• Agent-to-agent allow list: [PM agent ID], engineer, dev-fe, dev-be
• Chat completions: disabled

n8n_engineer (only if N8N confirmed in Step 3)

• Model (active): GLM-5.1
• Model (heartbeat): MiniMax M2.7
• Fallback: Qwen 3.6 Plus
• Repos: backend repo
• Agent-to-agent allow list: [PM agent ID], engineer, qa
• Chat completions: disabled

After all agents configured, verify:

openclaw agents list
Confirm all agents show configured status with correct models.

Step 5 — Asana Project Setup

If board does NOT exist yet

Create the Asana board manually:

1. Log into Asana → + New Project → name it: [project_name] → Board view
2. Create these columns in this exact order:
   - Backlog
   - PM Queue
   - Engineer Queue
   - Frontend Dev Queue
   - Backend Dev Queue
   - QA Queue
   [- N8N Engineer Queue — only if using N8N]
   - In Progress
   - QA Review
   - Complete
   - Blocked
3. Invite all agent Asana accounts as Members
4. Copy the project GID from the board URL
5. Share the GID here when ready

Once GID is confirmed

Using the Asana dependency skill, add project description to the board:

Project: [project_name]
PM Agent: [pm_agent_id]
Repos: FE: [fe_repo] | BE: [be_repo]
Asana Project GID: [GID]
Dev Manager Email env var: [env_var_name — label only]

Step 6 — Write Agent Workspace Files

Using the openclaw-administrator skill, write the following files for each agent.

HEARTBEAT.md (per agent — under 200 tokens): Project-specific heartbeat checklists referencing project GID and queue column to check.

USER.md (per agent):

• Role and scope
• Active Projects table: project name, PM agent ID, Asana GID, repo URLs
• Repo access scope for this agent
• Env var name labels for credential references (not values)
• Team agent roster with agent IDs

TOOLS.md (per agent):

• Available dependency skills
• Env var name label each skill uses for its credential
• sessions_send allowed targets

AGENTS.md (per agent) — must include an Active Projects section:

## Active Projects
- [project_name] — I am the [role] on this project.
  - Full rules: ~/.openclaw/projects/[project_name]/PROJECT.md
  - My queue: ~/.openclaw/projects/[project_name]/queues/to-[role].md
  - Shared workspace: ~/.openclaw/projects/[project_name]/workspace/
  - Check my queue at the start of every session before doing anything else.
  - Check project-lock.json to understand what phase we are in before acting.

Step 7 — Create Project Folder Structure

This is the coordination layer that makes agents work together across sprints. Read references/project-files.md for the full specification of each file's content and format.

Create the following structure for each project:

~/.openclaw/projects/[project_name]/
├── PROJECT.md                    ← Full team rulebook — every agent reads this
├── project.json                  ← Machine-readable config (agents, Asana, paths)
├── project-lock.json             ← Current phase and ownership
├── STATE.md                      ← Human-readable status at a glance
├── SHARED_MEMORY.md              ← Cross-agent knowledge not suited for Asana
├── DECISIONS.md                  ← Immutable log of all requirement decisions
├── KNOWN_ISSUES.md               ← Accepted technical debt and limitations
├── RUNBOOK.md                    ← How to run the project; branch and PR conventions
├── workspace/
│   ├── repo/                     ← The git repository (cloned here)
│   ├── mockups/                  ← Design mockups (fallback if Asana attachments unavailable)
│   ├── SPEC-CURRENT.md           ← Points to the active accepted spec
│   └── IMPLEMENTATION_GUIDE.md   ← Engineer's task-oriented implementation plan
└── queues/
    ├── to-pm.md
    ├── to-engineer.md
    ├── to-engineer-feasibility.md ← Requirements phase only — kept separate
    ├── to-qa.md
    └── to-operator.md

Creating Each File

project.json — fill in from the details collected in Step 1:

{
  "id": "[project_name]",
  "name": "[Project Display Name]",
  "asana": {
    "project_id": "[asana_project_gid]",
    "workspace_id": "[asana_workspace_gid]",
    "columns": {
      "backlog":     { "id": "[col_gid]", "purpose": "Work not yet started. PM creates tasks here." },
      "in_progress": { "id": "[col_gid]", "purpose": "Dev actively working on this." },
      "in_review":   { "id": "[col_gid]", "purpose": "PR submitted. QA should pick this up." },
      "qa":          { "id": "[col_gid]", "purpose": "QA is actively testing." },
      "completed":   { "id": "[col_gid]", "purpose": "QA passed. Awaiting operator merge and sign-off." },
      "blocked":     { "id": "[col_gid]", "purpose": "Waiting on client or external input. PM owns." }
    }
  },
  "participants": [
    { "agentId": "[pm_agent_id]", "workspace": "../../workspace-pm",     "role": "Project Manager" },
    { "agentId": "engineer",      "workspace": "../../workspace-main",   "role": "Lead Engineer" },
    { "agentId": "dev-fe",        "workspace": "../../workspace-dev0fe", "role": "Front-end Developer" },
    { "agentId": "dev-be",        "workspace": "../../workspace-dev0be", "role": "Back-end Developer" },
    { "agentId": "qa",            "workspace": "../../workspace-qa",     "role": "QA Engineer" }
  ],
  "shared_workspace": "./workspace",
  "repo_path": "./workspace/repo",
  "mockups_path": "./workspace/mockups",
  "shared_memory": "./SHARED_MEMORY.md",
  "decisions_log": "./DECISIONS.md",
  "known_issues": "./KNOWN_ISSUES.md",
  "runbook": "./RUNBOOK.md",
  "queues": {
    "pm":                   "./queues/to-pm.md",
    "engineer":             "./queues/to-engineer.md",
    "engineer_feasibility": "./queues/to-engineer-feasibility.md",
    "qa":                   "./queues/to-qa.md",
    "operator":             "./queues/to-operator.md"
  },
  "visual_assets": {
    "primary_storage": "asana_attachments",
    "fallback_storage": "./workspace/mockups",
    "naming_convention": "[task-id]-[short-description].[ext]",
    "vision_required_agents": ["engineer", "dev-fe", "qa"]
  },
  "escalation_rules": {
    "client_no_response_hours": 48,
    "dev_stuck_same_issue_escalations": 2,
    "dev_stuck_same_issue_hours": 24,
    "blocked_task_operator_escalation_hours": 48
  }
}

project-lock.json — initialize to idle:

{
  "phase": "idle",
  "sprint_id": null,
  "sprint_opened": null,
  "waiting_on": null,
  "last_updated": "[today's date]",
  "last_updated_by": "operator",
  "context": "Project initialized. Ready to receive first requirements.",
  "blocked_tasks": []
}

Initialize all queue files as empty with a header comment:

# Queue: to-[role]
# Format: [YYYY-MM-DD HH:MM] [FROM: agent-id] [TO: agent-id] [TASK: task-id or N/A]
# Queues are append-only. Archive at sprint close. Never delete entries.

Initialize STATE.md:

# [Project Display Name] — Current State
**Phase:** Idle — Ready for first requirements
**Last updated:** [today's date] by operator

Initialize SHARED_MEMORY.md, DECISIONS.md, KNOWN_ISSUES.md with a header and empty body.

Clone the repo and create mockups dir in ./workspace/:

cd ~/.openclaw/projects/[project_name]/workspace
git clone [repo_ssh_url] repo
mkdir -p mockups

Write PROJECT.md — read references/project-files.md for the full template and content rules. This is the most important file. Fill it in completely using the project details from Step 1 and the Asana column GIDs from Step 5.

Write RUNBOOK.md — stub it out now; the engineer fills in codebase details after their first session with the repo.

Step 8 — Credential Verification

Credential check — confirm in your secret management system:

- [ASANA_PAT_ENV_VAR_NAME] — Asana personal access token
- [GITHUB_PAT_ENV_VAR_NAME] — GitHub personal access token
- [DEV_MANAGER_EMAIL_ENV_VAR_NAME] — Dev Manager email address

Confirm they exist before continuing. (yes / one or more missing)

Step 9 — Enable Chat Completions

Using the openclaw-administrator skill, enable chat completions for the PM agent.

Step 10 — Smoke Test

SMOKE TEST

Step 1: Create a test task in the Asana PM Queue:
  Title: [TEST] Smoke test — verify agent pickup
  Description: Test task. Agent should acknowledge and move task or add a comment.

Step 2: Wait up to 30 minutes for the PM agent's next heartbeat.
  Watch for: task gaining a comment, or task moving to another column.

Step 3: Once PM confirmed working, send via chat completions:
  "Bug report for [project_name]: Login throws a 500 error when
   email field is left blank. Expected: show a validation error."

Step 4: Watch for task creation in the Engineer Queue on the Asana board.

Step 5: Confirm engineer picks up the task and produces an assessment.

Step 6: Verify the project folder exists and queue files are accessible by agents.

Heartbeat confirmed working? (yes / no — describe what happened)

Step 11 — Post-Setup Snapshot

If openclaw-recovery-manager is installed:

Taking post-setup snapshot.
Label: post-dev-team-setup-[today's date]-confirmed

Step 12 — Handoff Summary

TEAM SETUP COMPLETE

Project: [project_name]
Asana Project GID: [GID]
PM Agent: [pm_agent_id] — chat completions ENABLED
Project folder: ~/.openclaw/projects/[project_name]/

AGENTS:
Agent            | Primary Model         | Fallback         | Heartbeat       | Vision
[pm_agent_id]    | GLM-5.1               | MiniMax M2.7     | MiniMax M2.7    | —
engineer         | Gemini 3.1 Pro        | Claude Opus 4.7  | Gemini 3.1 Pro  | Native
dev-fe           | GLM-5.1               | Qwen 3.6 Plus    | GLM-5.1         | Gemini 3.1 Pro
dev-be           | GLM-5.1               | Qwen 3.6 Plus    | GLM-5.1         | —
qa               | Gemini 3.1 Pro        | GPT-5.5          | Gemini 3.1 Pro  | Native
[n8n_engineer]   | GLM-5.1               | Qwen 3.6 Plus    | MiniMax M2.7    | —

REPOS (SSH):
Frontend: [fe_repo]
Backend:  [be_repo]
Cloned to: ~/.openclaw/projects/[project_name]/workspace/repo/

HOW PROJECTS WORK:
- All agents read ~/.openclaw/projects/[project_name]/PROJECT.md for workflow rules
- Each agent checks their queue file at every session start
- Asana is the source of truth for task ownership and status
- project-lock.json tracks which phase the sprint is in
- One sprint at a time — PM does not accept new requirements until sprint is closed

TO START THE FIRST SPRINT:
  Send requirements to [pm_agent_id] via chat completions.
  The PM will open a feasibility discussion with the engineer,
  negotiate with the client, and open the sprint once requirements are accepted.

ADDING A NEW PROJECT:
- Run this skill again for the new project
- Add the new project to each shared agent's AGENTS.md Active Projects section
- Add the new PM to agent-to-agent allow lists
- Shared agents pick up new projects automatically on next heartbeat

RECOVERY:
Pre-setup:  pre-dev-team-setup-[date]
Post-setup: post-dev-team-setup-[date]-confirmed

Project Workflow Reference

For the complete workflow that agents follow after setup, see:

• references/workflow.md — All phases (requirements through sprint close), escalation rules, queue message format, git and branch conventions, QA process, operator merge procedure

Read this file when:

• Troubleshooting agent behavior during a sprint
• Answering operator questions about how the team works
• Explaining why an agent stopped work or escalated

Sprint Management

Opening a Sprint

The PM opens a sprint automatically when requirements are accepted by both the engineer and client. The PM updates project-lock.json phase to implementation and creates Asana tasks from the implementation guide.

During a Sprint

• Agents check project-lock.json phase before acting
• Devs work one branch per sprint, pushing updates — PR auto-updates each time
• QA re-reviews after each dev push
• Operator is notified via to-operator.md when QA passes all tasks

Closing a Sprint (Operator-Led)

When to-operator.md shows all tasks QA-passed:

1. Operator reviews and pulls the branch locally
2. Operator tells QA agent: "Merge to main"
3. QA merges the PR to main
4. All affected repos rebase to main
5. Operator confirms rebase is clean
6. Operator tells PM: "Sprint closed — ready for next requirements"
7. PM clears Asana, archives queue entries, updates STATE.md to idle
8. project-lock.json resets to idle

One sprint at a time. PM does not accept new requirements until project-lock.json is idle.

If Anything Goes Wrong

Option 1 — Recover using openclaw-recovery-manager:
  Restore: pre-dev-team-setup-[date]

Option 2 — Diagnose with openclaw-administrator:
  Run diagnostics and retry the failed step.

Option 3 — Describe what step failed and what error appeared.
  I can walk through the failed step again.