Skill: encryptshawn/build-dev-team (version 1.0.3)

--- name: build_development_team description: > Builds and configures a complete AI software development team inside OpenClaw, including the full project folder structure, agent coordination workflow, and vision-capable model handoffs for mockup-driven UI work. Use this skill whenever someone says "build a software development team", "set up my dev team", "configure the agent team", "set up a project", "add a project to my team", "how do agents work together on a project", "set up project coordination", "create a project folder", "wire up Asana for my team", "add mockup support to my dev team", or anything similar — even if they don't use the word "skill" or explicitly ask for setup. Also trigger when someone is troubleshooting a multi-agent dev setup, asking how PM/engineer/QA/devs should coordinate, or asking about sprint workflow, branch conventions, queue files, or project-lock state. This skill covers the full setup: safety snapshot, agent creation, model selection (with hallucination-aware picks and per-agent vision configuration), skills installation, Asana project setup, GitHub repo wiring, agent-to-agent communication, mockup storage convention (Asana attachments primary, project workspace fallback), and the complete project folder structure that coordinates agents across sprints — including PROJECT.md, project.json, queue files, shared workspace, spec versioning, decision logging, and sprint open/close procedures. Requires the openclaw-administrator skill (EncryptShawn) to be loaded. Recommends openclaw-recovery-manager (EncryptShawn) for safety. This skill does not make Asana or GitHub API calls itself — those are delegated to separately installed Asana and Git dependency skills. This skill does not read or store any credentials or secret values. --- # 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](#credential-and-security-model) - [Heartbeat Scheduling](#heartbeat-scheduling) - [Agent Workspace Files](#agent-workspace-files) - [Before You Start](#before-you-start--required-skills) - [Step 0 — Safety First](#step-0--safety-first) - [Step 1 — Gather Project Information](#step-1--gather-project-information) - [Step 2 — Model Selection](#step-2--model-selection) - [Step 3 — Skills Selection Per Agent](#step-3--skills-selection-per-agent) - [Step 4 — Agent Configuration](#step-4--agent-configuration) - [Step 5 — Asana Project Setup](#step-5--asana-project-setup) - [Step 6 — Write Agent Workspace Files](#step-6--write-agent-workspace-files) - [Step 7 — Create Project Folder Structure](#step-7--create-project-folder-structure) - [Step 8 — Credential Verification](#step-8--credential-verification) - [Step 9 — Enable Chat Completions](#step-9--enable-chat-completions) - [Step 10 — Smoke Test](#step-10--smoke-test) - [Step 11 — Post-Setup Snapshot](#step-11--post-setup-snapshot) - [Step 12 — Handoff Summary](#step-12--handoff-summary) - [Project Workflow Reference](#project-workflow-reference) - [Sprint Management](#sprint-management) - [If Anything Goes Wrong](#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. ### Heartbeat Model Selection Heartbeat runs must use the **cheapest available model**, not the agent's primary model. The selection priority is: 1. **If OpenRouter is configured** → use `openrouter/minimax/minimax-m2.7` (cheapest viable heartbeat model) 2. **If OpenRouter is NOT configured** → use the **cheapest model defined in that agent's config** — this must be identified during Step 4 and recorded in HEARTBEAT.md > **Why this matters:** Running a heartbeat on a primary model (e.g. Gemini 3.1 Pro or GLM-5.1) every 30 minutes burns significant credits for what is designed to be a near-stateless, fast check. The heartbeat model must be set independently of the agent's active/fallback models. ### Heartbeat Reasoning Level Heartbeat reasoning must be kept minimal. **Do not add a reasoning/thinking config key to openclaw.json** — that is not a supported heartbeat field. Instead, control reasoning level through the heartbeat prompt. Every HEARTBEAT.md must begin with: ``` /think:minimal ``` This forces the lightest reasoning path the model supports and prevents the agent from treating heartbeat like an active work session. ### Heartbeat Failure — Fail Cheap, Never Escalate to Primary If a heartbeat check fails (Asana unreachable, bad model config, tool error, etc.), the heartbeat **must stop immediately and fail cheaply**. It must NOT: - Retry using the agent's primary model - Spawn a troubleshooting loop - Use `sessions_send` to self - Continue reasoning about what might have gone wrong **The correct behavior on heartbeat failure:** log the failure (if logging is available), reply with a failure notice, and stop. The next scheduled heartbeat will try again. Do not spend primary model credits diagnosing heartbeat problems — those failures are almost always config issues (bad model path, credential not set, Asana connection error) that the operator must fix, not the agent. This must be documented in each agent's HEARTBEAT.md explicitly. --- ## 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., [REDACTED_SECRET]:org/repo-fe.git) - Backend repo: (e.g., [REDACTED_SECRET]: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.** **Heartbeat model rule:** If OpenRouter is configured, all agents use `openrouter/minimax/minimax-m2.7` for heartbeat regardless of their primary model. If OpenRouter is NOT available, use the cheapest model in the agent's config — confirm this during agent setup and record it explicitly in HEARTBEAT.md. ``` 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 | | (OpenRouter) | | 34% H% — lowest of all | | or cheapest avail. | engineer | Gemini 3.1 Pro | Claude Opus 4.7 | MiniMax M2.7 | Native (primary) | $2/$12 per 1M | (escalation) | (OpenRouter) | dev-fe | GLM-5.1 | Qwen 3.6 Plus | MiniMax M2.7 | Gemini 3.1 Pro | $1/$3.20 per 1M | | (OpenRouter) | (mockup tasks) dev-be | GLM-5.1 | Qwen 3.6 Plus | MiniMax M2.7 | — qa | Gemini 3.1 Pro | GPT-5.5 | MiniMax M2.7 | Native (primary) n8n_engineer | GLM-5.1 (active) | Qwen 3.6 Plus | MiniMax M2.7 | — | MiniMax M2.7 (heartbeat) | | (OpenRouter) | Heartbeat model rule: - All agents use openrouter/minimax/minimax-m2.7 for heartbeat IF OpenRouter is configured. - If OpenRouter is NOT configured, use the cheapest model in that agent's config. Confirm which model that is during agent setup and record it in HEARTBEAT.md. - Heartbeat reasoning is controlled via /think:minimal at the top of HEARTBEAT.md — not via any openclaw.json config key. 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 model: MiniMax M2.7 via OpenRouter (or cheapest available if no OpenRouter) - 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 model: MiniMax M2.7 via OpenRouter (or cheapest available if no OpenRouter) - 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 model: MiniMax M2.7 via OpenRouter (or cheapest available if no OpenRouter) - Heartbeat: every 30 minutes - 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 model: MiniMax M2.7 via OpenRouter (or cheapest available if no OpenRouter) - 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): Every HEARTBEAT.md must follow this exact template. Fill in the agent's specific project GID and queue/section GID during setup. The heartbeat must read these values directly — it must **not** perform Asana project discovery on every run. ```markdown /think:minimal # HEARTBEAT ## Asana Queue (read this, do not rediscover) - Project: [project_name] - Project GID: [asana_project_gid] - Queue/Section: [Agent Role] Queue - Queue/Section GID: [section_gid_if_known] ## On each heartbeat 1. Read the project GID and queue/section above — do not browse Asana to find your queue. 2. Query only that exact project + section. 3. Filter for tasks assigned to you only. 4. If no actionable task is assigned → reply HEARTBEAT_OK and stop. 5. If a task is assigned → report it and proceed per your role workflow. 6. If queue metadata above is missing or invalid → do one-time discovery, record the project GID and section GID here, then use that direct path from then on. ## Hard rules - Never use sessions_send to message yourself. - Never browse other projects, sections, or columns unless queue metadata is missing. - Never reason about missed or old heartbeats. - If this heartbeat fails (tool error, bad model config, Asana unreachable): log the failure and STOP. Do not retry. Do not escalate to your primary model. Do not troubleshoot. The next scheduled heartbeat will try again. ``` > **Note on section GID:** Retrieve the section GID during Step 5 when the Asana board is confirmed. Add it to HEARTBEAT.md at write time so the agent never has to discover it. If the GID isn't available at setup time, leave the field blank — the agent will do a one-time discovery on first heartbeat and write it in. **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: ```json { "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, [REDACTED_SECRET]: 2, "dev_stuck_same_issue_hours": 24, [REDACTED_SECRET]: 48 } } ``` **project-lock.json** — initialize to idle: ```json { "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**: ```markdown # [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/`: ```bash 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 | MiniMax M2.7* | Native dev-fe | GLM-5.1 | Qwen 3.6 Plus | MiniMax M2.7* | Gemini 3.1 Pro dev-be | GLM-5.1 | Qwen 3.6 Plus | MiniMax M2.7* | — qa | Gemini 3.1 Pro | GPT-5.5 | MiniMax M2.7* | Native [n8n_engineer] | GLM-5.1 | Qwen 3.6 Plus | MiniMax M2.7* | — * via OpenRouter. If OpenRouter not configured, cheapest available model as recorded in each agent's HEARTBEAT.md. 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. ```

path: _meta.json
content: ownerId: kn77nfg6wv2expv6qs7k17dfqs83zp59
slug: build-dev-team
version: 1.0.3
publishedAt: 1777265688262

path: references/project-files.md
content: # Project Files Reference

Full specification of every file in the `~/.openclaw/projects/[project_name]/` folder.

---

## Table of Contents

- [PROJECT.md — The Team Rulebook](#projectmd--the-team-rulebook)
- [project.json — Machine Config](#projectjson--machine-config)
- [project-lock.json — Phase Tracker](#project-lockjson--phase-tracker)
- [STATE.md — Human Status](#statemd--human-status)
- [SHARED_MEMORY.md — Cross-Agent Knowledge](#shared_memorymd--cross-agent-knowledge)
- [DECISIONS.md — Decision Log](#decisionsmd--decision-log)
- [KNOWN_ISSUES.md — Accepted Limitations](#known_issuesmd--accepted-limitations)
- [RUNBOOK.md — Project Setup Guide](#runbookmd--project-setup-guide)
- [workspace/SPEC-CURRENT.md](#workspacespec-currentmd)
- [workspace/IMPLEMENTATION_GUIDE.md](#workspaceimplementation_guidemd)
- [Queue Files](#queue-files)
- [File Responsibility Matrix](#file-responsibility-matrix)

---

## PROJECT.md — The Team Rulebook

**The most important file in the project folder.** Every participating agent has this injected into their context via their AGENTS.md. It is the single source of truth for how the team operates.

### Who reads it
All agents, at every session start (referenced from their AGENTS.md).

### Who writes it
Created by operator during setup. Updated by operator only when workflow rules change.

### Full Template

```markdown
# Project: [Project Display Name]

## The Team
- **PM Agent ([pm_agent_id])** — Client-facing. Owns requirements negotiation,
  Asana task creation, client communication, and sprint open/close.
- **Lead Engineer (engineer)** — Technical authority. Reviews feasibility, writes
  implementation guides, handles all technical escalations.
- **FE Dev (dev-fe)** — Implements front-end tasks from Asana. Escalates to Lead Engineer.
- **BE Dev (dev-be)** — Implements back-end tasks from Asana. Escalates to Lead Engineer.
- **QA Agent (qa)** — Validates PRs against the accepted spec. Merges on operator instruction.
- **Operator (Human)** — Final authority. Merges approval, unresolvable escalations, client engagement.

## Source of Truth

| What | Where |
|---|---|
| Task ownership and status | Asana |
| Accepted requirements | `workspace/SPEC-CURRENT.md` |
| Implementation approach | `workspace/IMPLEMENTATION_GUIDE.md` |
| Cross-agent knowledge | `SHARED_MEMORY.md` |
| Decision history | `DECISIONS.md` |
| Accepted limitations | `KNOWN_ISSUES.md` |
| Project setup / branch conventions | `RUNBOOK.md` |
| Current phase and ownership | `project-lock.json` |
| Human-readable status | `STATE.md` |

## Asana Columns

| Column | Meaning | Owner |
|---|---|---|
| Backlog | Work not yet started | PM creates tasks here |
| In Progress | Dev actively working | Dev owns |
| In Review | PR submitted, awaiting QA | QA picks up |
| QA | QA actively testing | QA owns |
| Completed | QA passed, awaiting operator | Operator reviews and merges |
| Blocked | Waiting on client/external | PM owns, escalates per rules |

## Git and Branch Convention

- **One repo copy** lives at `./workspace/repo/`
- **One active branch per dev per sprint**
  - Format: `[project-id]/[sprint-id]/[task-id]-[short-description]`
  - Example: `ezbi/sprint-3/1234-navbar-redesign`
- **After completing each task:** push to branch, PR opens (first task) or auto-updates (subsequent)
- **QA re-reviews after every push**
- **No new branches mid-sprint** unless operator explicitly approves a hotfix

## Mockups and Visual Assets

When a task involves a mockup, design comp, or visual reference:

- **Primary storage:** Asana task attachments. The Asana skill retrieves these.
- **Fallback storage:** `./workspace/mockups/` — used if Asana attachment retrieval is not available
- **Naming convention:** `[task-id]-[short-description].[ext]` (e.g. `1234-navbar-redesign.png`)
- **Task description must reference the mockup filename** so devs and QA can locate it

**Vision-required agents:**
- **Engineer** — uses vision (Gemini 3.1 Pro, native) when reviewing mockups during planning
  to write accurate implementation guides
- **FE Dev** — switches to its vision model (Gemini 3.1 Pro) when picking up a task whose
  Asana description references a mockup. Returns to GLM-5.1 for non-visual coding work.
- **QA** — uses vision (Gemini 3.1 Pro, native) when a PR includes UI changes that need to
  be compared visually against the mockup. QA is expected to compare rendered output to mockup.

If the FE dev cannot retrieve a referenced mockup from either Asana or `./workspace/mockups/`,
this is treated as a blocker — escalate to engineer per normal escalation rules.

## Workflow

### Phase 1: Requirements & Feasibility
1. PM receives or drafts client requirements
2. PM writes draft to `workspace/SPEC-v[N]-[YYYY-MM-DD].md`, updates `SPEC-CURRENT.md`
3. PM posts to `queues/to-engineer-feasibility.md` — "New spec draft ready"
4. Engineer reviews, posts all issues (numbered) to `queues/to-engineer-feasibility.md`
5. PM translates issues to non-technical language, sends to client via email or posts to
   `queues/to-operator.md` if email not configured
6. Client responds to each numbered issue: Accept / Provide solution / Descope
7. PM logs client response in `DECISIONS.md` verbatim with date
8. Engineer evaluates client solutions. Loop repeats until all issues resolved.
9. Engineer marks spec ACCEPTED in `SPEC-CURRENT.md`. PM logs in `DECISIONS.md`.
10. `project-lock.json` → phase: `planning`

**Client no-response rule:**
- No response in 48h → PM sends follow-up email
- Still no response → PM posts to `queues/to-operator.md`, task moves to Blocked

### Phase 2: Planning
1. Engineer writes `workspace/IMPLEMENTATION_GUIDE.md`
   - Task-oriented: each numbered section = one Asana task
   - Detailed enough to implement without ambiguity — no full code
   - Note items for `KNOWN_ISSUES.md`
2. Engineer updates `KNOWN_ISSUES.md` with accepted limitations
3. Engineer posts to `queues/to-pm.md` — "Implementation guide ready"
4. PM creates Asana tasks from guide, assigns to agents, places in Backlog
5. PM posts to `queues/to-engineer.md` — "Tasks created. Sprint [N] open."
6. `project-lock.json` → phase: `implementation`, sprint_id set

### Phase 3: Implementation
1. Dev picks up task from Backlog → moves to In Progress
2. Dev implements against `IMPLEMENTATION_GUIDE.md` and `RUNBOOK.md`
3. Dev checks `queues/to-[their-role].md` at session start

**Dev escalation rules:**
- If blocked: post to `queues/to-engineer.md` with task ID, what was tried, specific question
- Engineer responds in `queues/to-[dev-agent].md`
- If same issue escalated **2 times** to engineer without resolution, OR dev stuck **24 hours**:
  - Dev **stops work immediately**
  - Dev posts full summary to `queues/to-pm.md`
  - PM posts to `queues/to-operator.md`
  - Task moves to Blocked in Asana
  - **No further AI cycles on this task until operator resolves**

When task complete:
- Push to sprint branch. Open PR (first task) or PR auto-updates (subsequent).
- Move Asana task to In Review
- Post to `queues/to-qa.md` — task ID, PR link, brief description of changes

### Phase 4: QA
1. QA picks up tasks from In Review → moves to QA
2. QA reviews PR against:
   - `workspace/SPEC-CURRENT.md` — meets accepted requirements?
   - `KNOWN_ISSUES.md` — don't file failures against accepted limitations
   - `workspace/IMPLEMENTATION_GUIDE.md` — matches planned approach?
3. **Pass:** Move to Completed. Post to `queues/to-operator.md` — task ID, PR link, "QA passed."
4. **Fail:** Post specific numbered failures to `queues/to-engineer.md`. Move back to In Progress.

### Phase 5: Operator Review and Merge
1. Operator checks `queues/to-operator.md`
2. Operator pulls branch, reviews locally
3. If satisfied: tells QA — "Merge to main"
4. QA merges PR to main
5. QA/devs rebase all affected repos to main
6. Operator confirms rebase is clean
7. `project-lock.json` → phase: `sprint-close`

### Phase 6: Sprint Close
1. PM verifies all sprint tasks are Completed in Asana
2. PM archives completed tasks in Asana
3. PM verifies `DECISIONS.md` has full requirement decision record
4. PM verifies `KNOWN_ISSUES.md` is current
5. PM writes sprint summary to `SHARED_MEMORY.md`
6. PM updates `STATE.md` — "Sprint [N] closed. Ready for next requirements."
7. PM archives queue file entries (marks READ, does not delete)
8. `project-lock.json` → phase: `idle`
9. PM posts to `queues/to-operator.md` — "Sprint closed. Ready for next requirements."

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

## Escalation Rules Summary

| Situation | Action | Threshold |
|---|---|---|
| Client not responding | PM emails, then escalates to operator | 48h |
| Dev stuck on same task | Escalate to Lead Engineer | — |
| Same issue escalated 2x or 24h stuck | Stop work, PM escalates to operator | 24h |
| Task blocked with no movement | PM escalates to operator | 48h |

**No agent continues spending cycles on a blocked path. Stop, surface, wait.**

## Communication Protocol

All inter-agent messages go through the queue files in `queues/`.

**Message format — every entry must use this format:**
```
[YYYY-MM-DD HH:MM] [FROM: agent-id] [TO: agent-id] [TASK: asana-task-id or N/A]
Message body. Be specific. Include task IDs, file names, error messages where relevant.
---
```

- Queues are **append-only**. Never delete entries.
- Archive at sprint close (mark entries READ, do not remove lines).
- Each agent checks their queue at the **start of every session, before anything else**.
- Feasibility discussions go to `to-engineer-feasibility.md` only — separate from escalations.
```

---

## project.json — Machine Config

Machine-readable project configuration. Agents read this to resolve file paths,
Asana GIDs, and participant details without relying on hardcoded values.

### Who reads it
All agents.

### Who writes it
Created by operator during setup. Updated by operator only when structure changes.

### Notes
- All file paths use relative paths from the project root folder
- Asana column GIDs must be filled in from the actual Asana board after creation
- Escalation thresholds here are the canonical values — PROJECT.md references these conceptually but agents read the numbers from this file

---

## project-lock.json — Phase Tracker

Prevents agents from acting out of phase or moving forward when waiting on another agent or the operator.

### Who reads it
All agents check this at session start before taking any action.

### Who writes it
PM (most phase transitions), Engineer (planning → implementation), QA (after merge), Operator (sprint-close → idle).

### Valid phase progression
`idle` → `requirements` → `planning` → `implementation` → `qa` → `sprint-close` → `idle`

### Format
```json
{
  "phase": "idle",
  "sprint_id": null,
  "sprint_opened": null,
  "waiting_on": null,
  "last_updated": "YYYY-MM-DD",
  "last_updated_by": "agent-id or operator",
  "context": "Human-readable description of current state",
  "blocked_tasks": []
}
```

### Agent behavior rules
- If `phase` does not match the agent's expected action → stop and post to relevant queue
- If `waiting_on` is not null and is this agent → act immediately on session start
- If `blocked_tasks` is non-empty and contains this agent's task → treat as stopped

---

## STATE.md — Human Status

The operator's one-file status check. Updated by agents at key moments so the operator
can understand project state without digging through Asana or queue files.

### Who reads it
Operator primarily. Agents may read it for context.

### Who writes it
All agents update it when they complete a significant action.

### Format
```markdown
# [Project Name] — Current State
**Phase:** [phase] ([sprint_id if applicable])
**Last updated:** [YYYY-MM-DD HH:MM] by [agent-id]

## Sprint Progress
- ✅ Task [ID] — [description] (merged)
- 🔄 Task [ID] — [description] (in progress, [agent])
- ⏳ Task [ID] — [description] (backlog)
- 🚫 Task [ID] — [description] (blocked — [reason])

## Operator Queue Summary
[List of items in to-operator.md awaiting action]
```

---

## SHARED_MEMORY.md — Cross-Agent Knowledge

A living document for project knowledge that needs to persist across sessions
but doesn't belong in Asana.

### What goes here
- Codebase quirks and patterns relevant to this project
- Client preferences and communication style notes
- Things learned mid-sprint that other agents should know
- Sprint-close summaries (added by PM at close)

### What does NOT go here
- Task status → Asana
- Accepted requirements → SPEC files
- Implementation approach → IMPLEMENTATION_GUIDE.md
- Decisions and client acceptances → DECISIONS.md

### Format
Free-form markdown. Agents append new information with a date prefix:
```markdown
## [YYYY-MM-DD] [agent-id] — [topic]
Content here.
```

---

## DECISIONS.md — Decision Log

An **immutable, append-only** record of every significant decision made during
requirements negotiation. Never edit or delete existing entries.

### Who reads it
PM, Engineer, Operator. QA references when filing failures.

### Who writes it
PM only. Written during requirements phase as decisions are made.

### Purpose
When a client later says "we never agreed to that," this file is the record.
It captures what was proposed, what issue was surfaced, what the client said, and what was accepted.

### Format
```markdown
## [YYYY-MM-DD] — [Sprint ID]: [Decision Topic]

**Issue surfaced by engineer:** [description of technical issue or conflict]

**Client response (received [date]):** [exact client words or paraphrase, clearly attributed]

**Resolution:** [Accept as known outcome / Client-proposed alternative / Descoped]

**Accepted by:** [Client name], [engineer agent], [pm agent]
**Logged by:** [pm agent]
---
```

---

## KNOWN_ISSUES.md — Accepted Limitations

Documents accepted technical debt and known limitations so QA does not file
failures against intentional decisions, and clients cannot later claim ignorance.

### Who reads it
QA (before every test run), all agents for context, operator.

### Who writes it
Engineer, updated during planning phase and as new limitations are accepted.

### Format
```markdown
## [Sprint ID] — [Issue Title]
- **Accepted:** [date]
- **Context:** [why this limitation exists and what decision led to it]
- **Impact:** [what users or developers will experience as a result]
---
```

---

## RUNBOOK.md — Project Setup Guide

Written and maintained by the Lead Engineer. Devs and QA read this before
starting work on any task to avoid unnecessary escalations.

### Who reads it
All agents before starting work, operator for deployment reference.

### Who writes it
Engineer creates initial stub during setup. Engineer fills in details after
their first session with the repo. Engineer updates as patterns evolve.

### Minimum contents
```markdown
# [Project Name] Runbook

## Local Setup
[How to install dependencies and run the project locally]

## Branch Naming Convention
[project-id]/[sprint-id]/[task-id]-[short-description]
Example: ezbi/sprint-3/1234-navbar-redesign

## PR Conventions
- Title: [[PROJECT-task-id]] Short description
- Body must include: task ID, what changed, how to test, Asana task link

## Known Codebase Patterns
[Common patterns in use — component structure, API conventions, etc.]

## Known Gotchas
[Things that trip up developers — quirky dependencies, env requirements, etc.]

## Deployment Notes
[Steps needed to deploy after merge if applicable]
```

---

## workspace/SPEC-CURRENT.md

A reference that always points to (or contains) the currently active accepted specification.

### Versioning rules
- Every new requirements draft gets its own versioned file: `SPEC-v[N]-[YYYY-MM-DD].md`
- Specs are **never overwritten** — always increment the version number
- `SPEC-CURRENT.md` is updated to point to or contain the latest accepted spec
- The version history is the audit trail

### Status markers
Engineer adds one of these markers at the top when reviewing:
```
STATUS: DRAFT — Under feasibility review
STATUS: ACCEPTED — [date] — [engineer agent] + [pm agent]
```

---

## workspace/IMPLEMENTATION_GUIDE.md

Written by the Lead Engineer after spec is accepted. The task-oriented blueprint
for what needs to be built and how.

### Format rules
- Each numbered section = one Asana task
- Describe approach, files affected, edge cases, dependencies, acceptance criteria
- No full code — approach-level only
- Reference `KNOWN_ISSUES.md` items created from this guide

### Structure
```markdown
# Implementation Guide — [Sprint ID]

## Task 1: [Task Title]
**Assigned to:** [agent role]
**Asana task:** [created by PM after this guide is written]

### What to build
[Description]

### Files affected
[List of files or components]

### Approach
[How to implement it — no full code]

### Acceptance criteria
[How QA will verify this is complete]

### Notes / edge cases
[Anything the dev should know]
---

## Task 2: ...
```

---

## Queue Files

Located in `queues/`. One file per recipient.

| File | Purpose |
|---|---|
| `to-pm.md` | Messages for PM — from engineer (issues ready), from QA (task failures), from devs (stuck escalations) |
| `to-engineer.md` | Messages for Lead Engineer — dev escalations, PM implementation requests |
| `to-engineer-feasibility.md` | Requirements phase only — keeps feasibility back-and-forth separate from escalations |
| `to-qa.md` | Messages for QA — dev task completions with PR links |
| `to-operator.md` | Messages for human operator — QA passes, blocks, client no-response, unresolvable escalations |

### Queue message format (required for every entry)
```
[YYYY-MM-DD HH:MM] [FROM: agent-id] [TO: agent-id] [TASK: asana-task-id or N/A]
Message body. Be specific. Include task IDs, file names, error messages.
---
```

### Queue rules
- Append-only — never delete entries
- Mark entries READ (prepend `[READ]`) when processed — do not remove lines
- Archive at sprint close
- Check your own queue at the start of every session, before any other action

---

## File Responsibility Matrix

| File | Created by | Updated by | Read by | Mutable? |
|---|---|---|---|---|
| `PROJECT.md` | Operator | Operator only | All agents | Rarely |
| `project.json` | Operator | Operator only | All agents | On structure change |
| `project-lock.json` | Operator | PM, Engineer, QA, Operator | All agents | Every phase change |
| `STATE.md` | Operator | All agents | Operator, all agents | Frequently |
| `SHARED_MEMORY.md` | Operator | All agents (append) | All agents | Frequently |
| `DECISIONS.md` | PM | PM only (append) | PM, Engineer, Operator | Append-only |
| `KNOWN_ISSUES.md` | Engineer | Engineer (append) | QA, all agents | Append-only |
| `RUNBOOK.md` | Engineer | Engineer | Devs, QA | As patterns evolve |
| `SPEC-vN-*.md` | PM | Never | PM, Engineer | Immutable |
| `SPEC-CURRENT.md` | PM | PM (points to latest) | All agents | Per sprint |
| `IMPLEMENTATION_GUIDE.md` | Engineer | Engineer | All devs, QA | Per sprint |
| `queues/to-*.md` | Operator (init) | Named sender (append) | Named recipient | Append-only |


path: references/workflow.md
content: # Workflow Reference

Complete agent workflow for projects managed under this team setup.
Read this when troubleshooting agent behavior, explaining the workflow to an operator,
or verifying an agent is acting correctly for the current phase.

---

## Table of Contents

- [Phase Overview](#phase-overview)
- [Phase 1: Requirements and Feasibility](#phase-1-requirements-and-feasibility)
- [Phase 2: Planning](#phase-2-planning)
- [Phase 3: Implementation](#phase-3-implementation)
- [Phase 4: QA](#phase-4-qa)
- [Phase 5: Operator Review and Merge](#phase-5-operator-review-and-merge)
- [Phase 6: Sprint Close](#phase-6-sprint-close)
- [Escalation Rules](#escalation-rules)
- [Git and Branch Conventions](#git-and-branch-conventions)
- [Queue Message Format](#queue-message-format)
- [Agent Session Start Checklist](#agent-session-start-checklist)

---

## Phase Overview

```
idle → requirements → planning → implementation → sprint-close → idle
                                       ↕
                                      qa
```

Each phase is tracked in `project-lock.json`. Agents check this file before acting.
If the current phase does not match the agent's intended action, the agent stops and
posts to their relevant queue rather than proceeding.

---

## Phase 1: Requirements and Feasibility

**Owner:** PM Agent  
**Lock phase:** `requirements`  
**Queue used:** `to-engineer-feasibility.md` (kept separate from implementation escalations)

### Steps

1. PM receives or drafts client requirements.
2. PM creates a new versioned spec file: `workspace/SPEC-v[N]-[YYYY-MM-DD].md`
   - Never overwrite an existing spec — always increment the version number
   - Updates `SPEC-CURRENT.md` to reference this draft
   - Marks file: `STATUS: DRAFT — Under feasibility review`
3. PM posts to `queues/to-engineer-feasibility.md`:
   ```
   [date] [FROM: pm] [TO: engineer] [TASK: N/A]
   New spec draft ready for feasibility review.
   File: workspace/SPEC-v[N]-[YYYY-MM-DD].md
   ---
   ```
4. Engineer reads the spec and reviews for:
   - Technical feasibility
   - Conflicts with existing architecture
   - Ambiguities that would block implementation
   - Missing information the devs would need
5. Engineer posts all issues to `queues/to-engineer-feasibility.md` — **numbered**, specific, with options where possible:
   ```
   [date] [FROM: engineer] [TO: pm] [TASK: N/A]
   Feasibility review complete. 3 issues to resolve before accepting.

   Issue 1: [title]
   [description of the technical issue, concrete impact, and options if available]

   Issue 2: ...
   ---
   ```
6. PM translates each issue into non-technical language.
   - If email is configured: sends to client directly
   - If not configured: posts to `queues/to-operator.md` with message ready for operator to relay
7. Client responds to each numbered issue:
   - **Accept as known outcome** — client accepts the limitation as-is
   - **Provide a solution** — client proposes an alternative
   - **Descope** — remove the requirement causing the issue
8. PM logs client response in `DECISIONS.md` verbatim with date (see format in project-files.md).
9. If client proposes a solution, engineer evaluates it. This loop repeats until all issues resolved.
10. When all issues resolved:
    - Engineer updates `SPEC-CURRENT.md`: `STATUS: ACCEPTED — [date] — [engineer] + [pm]`
    - PM logs final acceptance in `DECISIONS.md`
    - PM updates `project-lock.json` → `phase: planning`

### Client No-Response Rule
- No response in **48 hours** → PM sends follow-up via email
- Still no response → PM posts to `queues/to-operator.md`:
  ```
  [date] [FROM: pm] [TO: operator] [TASK: N/A]
  Client has not responded to feasibility issues for 48h. Follow-up sent.
  Please engage client directly. Issues are in queues/to-engineer-feasibility.md.
  ---
  ```
- Task moves to Blocked in Asana until resolved

---

## Phase 2: Planning

**Owner:** Lead Engineer  
**Lock phase:** `planning`

### Steps

1. Engineer writes `workspace/IMPLEMENTATION_GUIDE.md` (see format in project-files.md).
   - Each numbered section = one Asana task
   - Task-oriented and detailed enough to implement without ambiguity
   - No full code — approach, files affected, edge cases, acceptance criteria
   - Notes items for `KNOWN_ISSUES.md`
   - **If the spec includes mockups:** engineer uses its vision capability (Gemini 3.1 Pro)
     to review them. Each task that references a mockup must include the mockup filename
     in its task section so the FE dev and QA can locate it later.
2. Engineer updates `KNOWN_ISSUES.md` with any limitations accepted during requirements phase.
3. Engineer posts to `queues/to-pm.md`:
   ```
   [date] [FROM: engineer] [TO: pm] [TASK: N/A]
   Implementation guide ready. workspace/IMPLEMENTATION_GUIDE.md
   [N] tasks defined.
   ---
   ```
4. PM reviews guide for completeness (can each section become a clear Asana task?).
5. PM creates Asana tasks from guide:
   - One task per numbered section
   - Task description includes the relevant guide section text
   - Tasks placed in Backlog, assigned to appropriate agents
6. PM posts to `queues/to-engineer.md`:
   ```
   [date] [FROM: pm] [TO: engineer] [TASK: N/A]
   Sprint [N] open. [X] tasks created in Asana Backlog.
   ---
   ```
7. PM updates `project-lock.json`:
   ```json
   {
     "phase": "implementation",
     "sprint_id": "sprint-[N]",
     "sprint_opened": "[date]"
   }
   ```
8. PM updates `STATE.md` to reflect sprint open status.

---

## Phase 3: Implementation

**Owner:** Devs (their assigned tasks)  
**Escalation owner:** Lead Engineer  
**Lock phase:** `implementation`

### Dev Task Flow

1. Dev picks up assigned task from Backlog → moves to In Progress in Asana.
2. Dev reads:
   - `workspace/IMPLEMENTATION_GUIDE.md` — the relevant task section
   - `RUNBOOK.md` — codebase conventions and gotchas
   - Their queue (`queues/to-[role].md`) — any pending messages
3. **If the task references a mockup (FE dev only):**
   - Dev switches to its vision model (Gemini 3.1 Pro) for this task
   - Retrieves the mockup from Asana attachments (preferred) or `./workspace/mockups/`
   - If mockup cannot be retrieved from either source, treat as a blocker —
     escalate to engineer per normal escalation rules
4. Dev implements in the sprint branch:
   - Branch format: `[project-id]/[sprint-id]/[task-id]-[short-description]`
   - Dev works in `workspace/repo/` on their branch
5. When task is complete:
   - Push to sprint branch
   - **First task of sprint:** open a PR
   - **Subsequent tasks:** push updates — existing PR auto-updates
   - Move Asana task from In Progress → In Review
   - Post to `queues/to-qa.md`:
     ```
     [date] [FROM: dev-fe] [TO: qa] [TASK: 1234]
     Task 1234 complete. Branch: ezbi/sprint-3/1234-navbar-redesign
     PR: [PR URL]
     What changed: [brief description]
     ---
     ```
6. Dev moves on to next Backlog task if available.

### Dev Escalation Rules

**When blocked:**
- Post to `queues/to-engineer.md`:
  ```
  [date] [FROM: dev-fe] [TO: engineer] [TASK: 1234]
  Blocked on task 1234.
  Attempted: [what was tried]
  Question: [specific question]
  ---
  ```
- Engineer responds in `queues/to-[dev-agent].md`
- Dev waits for response before continuing on this specific issue

**Hard stop rule — triggers when EITHER condition is met:**
- Same issue escalated to engineer **2 times** without resolution, OR
- Dev has been actively stuck on the same issue for **24 hours**

**When hard stop triggers:**
1. Dev **stops work immediately** on that task
2. Dev posts full summary to `queues/to-pm.md`:
   ```
   [date] [FROM: dev-fe] [TO: pm] [TASK: 1234]
   HARD STOP — Task 1234 escalation limit reached.
   Issue: [description]
   Escalation history:
     [date] — First escalation to engineer: [question]
     [date] — Engineer response: [response]
     [date] — Second escalation to engineer: [question]
     [date] — Engineer response: [response]
   Still blocked because: [reason]
   Awaiting operator assistance before resuming.
   ---
   ```
3. Task moves to Blocked in Asana
4. PM posts to `queues/to-operator.md`
5. **No further AI cycles spent on this task until operator resolves**

---

## Phase 4: QA

**Owner:** QA Agent  
**Lock phase:** `implementation` (QA runs concurrently)

### QA Task Flow

1. QA picks up task from In Review → moves to QA in Asana.
2. QA reads:
   - `KNOWN_ISSUES.md` — do not file failures against accepted limitations
   - `workspace/SPEC-CURRENT.md` — accepted requirements
   - `workspace/IMPLEMENTATION_GUIDE.md` — planned approach for this task
3. **If the PR includes UI changes and the task references a mockup:**
   - QA uses its vision capability (Gemini 3.1 Pro, native) to compare
     rendered UI against the referenced mockup
   - Visual deviations from the mockup that are not noted in `KNOWN_ISSUES.md`
     are QA failures
   - Retrieve mockup via Asana attachment (preferred) or `./workspace/mockups/`
4. QA reviews the PR against all references.

### QA Pass
```
[date] [FROM: qa] [TO: operator] [TASK: 1234]
Task 1234 — QA PASSED.
PR: [PR URL]
Branch: [branch name]
Verified against: SPEC-CURRENT.md + IMPLEMENTATION_GUIDE.md task 1
No known issues flagged.
---
```
- Move task to Completed in Asana.

### QA Fail
```
[date] [FROM: qa] [TO: engineer] [TASK: 1234]
Task 1234 — QA FAILED. [N] issues found.

Issue 1: [specific description — what was tested, what was expected, what happened]
Issue 2: ...
---
```
- Move task back to In Progress in Asana.
- Dev addresses failures, re-pushes. PR auto-updates. QA re-reviews.

---

## Phase 5: Operator Review and Merge

**Owner:** Operator (Human)  
**Lock phase:** `sprint-close` (after merge)

### Flow

1. Operator reviews `queues/to-operator.md` for QA-passed tasks.
2. Operator pulls the branch locally and reviews.
3. If satisfied: Operator tells QA agent — "Merge to main."
4. QA agent merges the PR to main.
5. QA agent (or devs) rebase all affected repos to main:
   ```bash
   git checkout main
   git pull
   git checkout [sprint-branch]
   git rebase main
   ```
6. Operator confirms rebase is clean — no conflicts, CI passes.
7. Operator updates `project-lock.json` → `phase: sprint-close`.

---

## Phase 6: Sprint Close

**Owner:** PM Agent  
**Lock phase:** `idle` (after close)

### Close Checklist

1. PM verifies all sprint tasks are in Completed in Asana.
2. PM archives completed tasks in Asana (close/archive — do not delete).
3. PM verifies `DECISIONS.md` has a complete record for this sprint.
4. PM verifies `KNOWN_ISSUES.md` is current with all accepted limitations.
5. PM writes sprint summary to `SHARED_MEMORY.md`:
   ```markdown
   ## [YYYY-MM-DD] Sprint [N] Close — pm-agent
   What was built: [summary]
   Issues accepted: [reference to KNOWN_ISSUES entries]
   Client sign-off: [yes/no — how confirmed]
   Carry-over notes: [anything relevant for the next sprint]
   ```
6. PM updates `STATE.md`:
   ```markdown
   # [Project Name] — Current State
   **Phase:** Idle — Sprint [N] closed. Ready for next requirements.
   **Last updated:** [date] by [pm-agent]
   ```
7. PM archives queue entries — prepend `[READ]` to processed entries. Do not delete lines.
8. PM updates `project-lock.json`:
   ```json
   {
     "phase": "idle",
     "sprint_id": null,
     "sprint_opened": null,
     "waiting_on": null,
     "last_updated": "[date]",
     "last_updated_by": "[pm-agent]",
     "context": "Sprint [N] closed. Ready for next requirements.",
     "blocked_tasks": []
   }
   ```
9. PM posts to `queues/to-operator.md`:
   ```
   [date] [FROM: pm] [TO: operator] [TASK: N/A]
   Sprint [N] closed. Asana clean. All queues archived.
   Ready to receive next set of requirements.
   ---
   ```

**PM does not accept new requirements until project-lock.json phase is idle.**

---

## Escalation Rules

| Situation | Action | Threshold |
|---|---|---|
| Client not responding to requirements | PM emails, then posts to to-operator.md | 48h no response |
| Dev blocked on task | Dev posts to to-engineer.md | Immediately when blocked |
| Same issue escalated 2x to engineer | Dev hard stop, PM posts to to-operator.md | 2 escalations |
| Dev stuck same issue | Dev hard stop, PM posts to to-operator.md | 24h active stuck |
| Task in Blocked with no movement | PM posts to to-operator.md | 48h |
| QA failing same task repeatedly | QA posts to to-engineer.md; PM monitors | — |

**No agent continues spending AI cycles on a blocked path. Stop, surface, wait.**

---

## Git and Branch Conventions

### Branch naming
```
[project-id]/[sprint-id]/[task-id]-[short-description]
```
Examples:
```
ezbi/sprint-3/1234-navbar-redesign
ezbi/sprint-3/1235-settings-migration
ezbi/sprint-3/1236-avatar-dropdown
```

### One branch per dev per sprint
- Dev works all their sprint tasks on a single branch
- Push after completing each task — PR auto-updates
- QA reviews the PR again after each push

### Hotfix branches (operator approval required)
- Only when a fix must ship independently of the current sprint
- Operator explicitly approves before dev creates a new branch
- Goes through the same QA → operator → merge flow

### PR conventions
- Title: `[[PROJECT-task-id]] Short description`
- Body must include:
  - Task ID
  - Asana task link
  - What changed (brief)
  - How to test
- One PR per dev per sprint — it accumulates all tasks as dev pushes

### After merge
1. QA merges PR to main (on operator instruction)
2. All affected repos rebase to main
3. Operator confirms clean

---

## Queue Message Format

Every queue entry must use this exact format:

```
[YYYY-MM-DD HH:MM] [FROM: agent-id] [TO: agent-id] [TASK: asana-task-id or N/A]
Message body. Be specific. Include task IDs, file names, error messages where relevant.
If multiple items, number them clearly.
---
```

### Rules
- Queues are append-only — never delete entries
- When processed, prepend `[READ]` to the entry — do not remove the line
- Archive at sprint close (mark READ, do not remove)
- Each agent checks their queue at session start before any other action
- `to-engineer-feasibility.md` is used **only** during requirements phase — keep it separate from escalations

---

## Agent Session Start Checklist

Every agent runs this at the start of every session:

1. Read `project-lock.json` — what phase are we in?
2. Read `queues/to-[my-role].md` — any pending messages?
3. If there are unread queue messages, address them before starting new work
4. If phase does not match my expected action, post to relevant queue and wait
5. If phase matches and no pending messages, proceed with current work

**The queue and phase check always comes before anything else.**


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)