Skill: encryptshawn/openclaw-projects (version 1.0.1)

--- name: openclaw_projects description: > Builds a Project — a coordinated multi-agent team setup — inside OpenClaw, for any kind of team: software development, marketing, real estate, content, sales, operations, research, customer success, or anything else where multiple agents need to work together toward shared goals. Use this skill whenever someone says "set up a project", "create a project", "add a project to my team", "build a team", "make my agents work together", "configure agent coordination", "set up agent collaboration", "I want a team of agents", "how do I run multiple agents on one project", "wire up Asana for my agents", "wire up ClickUp for my agents", "add a new project", or anything similar — even if they don't explicitly say "project" or "team". Also trigger when someone asks how multiple agents should coordinate, share work, escalate, or hand off tasks. This skill creates the entire project folder structure (PROJECT.md rulebook, project.json config, queue files for inter-agent messaging, project-lock.json phase tracking, decision/issue/runbook documents, shared workspace) and updates OpenClaw config to wire agent-to-agent communication. It works through a structured interview: team identity, work structure, then a comprehensive AI-rewritten team plan for user review and fine-tuning before building. Supports any task manager backend (Asana, ClickUp) via the user's separately installed dependency skill. Multiple projects can coexist; agents can participate in multiple projects. Requires the openclaw-administrator skill (EncryptShawn) to be loaded. Recommends openclaw-recovery-manager (EncryptShawn) for safety. This skill does not make task-manager API calls itself — those are delegated to the user's installed Asana or ClickUp dependency skill. This skill does not read or store any credentials or secret values. --- # OpenClaw Projects This skill adds the concept of a **Project** to OpenClaw — a coordinated multi-agent team setup that lets one or more agents work together toward shared goals. Projects can be any team type: software development, marketing, real estate, content, sales, customer success, research, or anything else. A Project is: - A folder at `~/.openclaw/projects/[project-id]/` containing the team rulebook, configuration, shared workspace, and inter-agent message queues - A defined workflow that takes work from intake through delivery - A wiring layer that connects multiple agents through OpenClaw's agent-to-agent communication - A coordination unit that uses one task manager (Asana or ClickUp) as the source of truth for task ownership and status Multiple projects can coexist. Agents can participate in multiple projects. --- ## Contents - [What This Skill Does](#what-this-skill-does) - [Prerequisites](#prerequisites) - [Credential and Security Model](#credential-and-security-model) - [Heartbeat Model and Behavior Rules](#heartbeat-model-and-behavior-rules) - [Step 0 — Safety First](#step-0--safety-first) - [Step 1 — Discover Existing Setup](#step-1--discover-existing-setup) - [Step 2 — Pass 1: Team Identity Interview](#step-2--pass-1-team-identity-interview) - [Step 3 — Pass 2: Work Structure Interview](#step-3--pass-2-work-structure-interview) - [Step 4 — Pass 3: AI-Drafted Team Plan for Review](#step-4--pass-3-ai-drafted-team-plan-for-review) - [Step 5 — Capability Check](#step-5--capability-check) - [Step 6 — Task Manager Setup](#step-6--task-manager-setup) - [Step 7 — Create Project Folder Structure](#step-7--create-project-folder-structure) - [Step 8 — Update Agent Workspaces](#step-8--update-agent-workspaces) - [Step 9 — Update OpenClaw Config](#step-9--update-openclaw-config) - [Step 10 — Smoke Test](#step-10--smoke-test) - [Step 11 — Post-Setup Snapshot and Handoff](#step-11--post-setup-snapshot-and-handoff) - [If Anything Goes Wrong](#if-anything-goes-wrong) Reference files (read when needed): - `references/project-files.md` — Full specification of every project folder file - `references/workflow.md` — Universal workflow phases, escalation rules, queue formats - `references/interview-questions.md` — Full interview question banks for Pass 1 and Pass 2 - `references/team-archetypes.md` — Common team patterns to draw on for examples - `references/templates.md` — Parameterized templates for every file this skill generates (PROJECT.md, project.json, queue files, etc.) plus a placeholder reference table --- ## What This Skill Does 1. **Interviews the user** through a structured three-pass discovery process to understand the team 2. **Drafts a comprehensive team plan** — AI-rewrites the user's answers into a complete operational plan, filling gaps and tightening loose answers 3. **Reviews the plan with the user** for fine-tuning and approval before building 4. **Checks agent capabilities** against the planned work and surfaces any concerns (e.g., a vision-required task assigned to an agent without a vision-capable model) 5. **Creates the project folder** at `~/.openclaw/projects/[project-id]/` with all coordination files 6. **Updates each participating agent's workspace** with project references in their AGENTS.md 7. **Updates OpenClaw config** to enable agent-to-agent communication between project participants 8. **Walks through a smoke test** to verify the project is operational ## What This Skill Does NOT Do - Create agents — agents must already exist (use OpenClaw's agent creation flow first) - Choose models for agents — that's the user's decision, made when creating the agent - Hold credentials — the task manager dependency skill handles that - Make task manager API calls directly — delegated to the user's Asana or ClickUp skill --- ## Prerequisites **Must be installed before running this skill:** - **openclaw-administrator** (EncryptShawn) — used to update OpenClaw config and write workspace files **Must already exist in OpenClaw:** - Each agent that will participate in the project - Each agent must have a model and fallback configured (this skill verifies but does not set models) **Must be installed on the agents that will use it:** - A task manager dependency skill — either Asana or ClickUp — installed on every agent that needs to read/write tasks. The user is responsible for installing this and configuring its credential (PAT, API key, or token) in their secret management system. **Strongly recommended:** - **openclaw-recovery-manager** (EncryptShawn) — provides config snapshots and rollback **If the user has not yet created their agents**, stop and tell them: > "Before we build a project, you need to create the agents that will participate in it. Each agent should have its model and fallback configured, and you should install the task manager skill (Asana or ClickUp) on each agent that will read or write tasks. Once your agents exist, come back and we'll set up the project." --- ## Heartbeat Model and Behavior Rules These rules apply to **every agent on every project created by this skill.** They must be reflected in each agent's HEARTBEAT.md (written in Step 8). ### Heartbeat model selection Heartbeat runs must use the cheapest available model, not the agent's primary or fallback model. Primary models are expensive for what a heartbeat is — a near-stateless task-manager queue check. Selection priority: 1. **If OpenRouter is configured on the agent** → use `openrouter/minimax/minimax-m2.7` 2. **If OpenRouter is NOT configured** → use the cheapest model defined in that agent's config. Identify this during Step 8 and record it explicitly in HEARTBEAT.md. ### Heartbeat reasoning level Heartbeat reasoning must be kept minimal. Do not add a reasoning config key to openclaw.json — that is not a supported field. Control it through the heartbeat prompt instead. Every HEARTBEAT.md must begin with: ``` /think:minimal ``` ### Heartbeat failure — fail cheap, never escalate If a heartbeat fails (task manager unreachable, bad model config, tool error, anything), the agent must **stop immediately and fail cheaply.** It must NOT: - Retry using the primary model - Start a troubleshooting loop - Use `sessions_send` to message itself - Reason about what went wrong The correct behavior: log the failure if logging is available, and stop. The next scheduled heartbeat will try again. Most heartbeat failures are config problems (bad model path, missing credential, task manager connection error) that the operator must fix — not something the agent can resolve by spending primary model credits every 30 minutes. --- ## Credential and Security Model **This skill never reads, stores, requests, or transmits credential values.** This skill collects only the *names* of env vars (e.g., `PROJ_ASANA_PAT`) — never their values. The dependency skills the user installed (Asana skill, ClickUp skill, any other domain-specific skill) hold and use credentials. This skill passes credential env var *names* to those skills so they know which value to pull from the agent runtime environment. Credentials must be stored in the user's secret management system (Kubernetes ConfigMap/Secret, .env file, or equivalent) before this skill runs. --- ## Step 0 — Safety First 1. Check if **openclaw-recovery-manager** is installed. - **Yes:** Take a snapshot. Label: `pre-project-setup-[project-id]-[date]` - **No:** Ask: > "I recommend installing openclaw-recovery-manager (EncryptShawn on ClawHub) before we proceed — it lets us roll back if anything goes wrong. Want to install it first, or proceed without it?" --- ## Step 1 — Discover Existing Setup Before interviewing, gather context using openclaw-administrator: 1. List existing agents and their configured models 2. List existing projects in `~/.openclaw/projects/` (if any) 3. Check which task manager skills are installed on each agent (Asana, ClickUp, or both) This context informs the interview — for example, if the user has 5 agents already, you can show them the list to pick from rather than asking them to type names. If `~/.openclaw/projects/` doesn't exist yet, this is the first project. Note this — the agents won't have any "Active Projects" section in their AGENTS.md yet. --- ## Step 2 — Pass 1: Team Identity Interview Read `references/interview-questions.md` for the full question bank. The goal of Pass 1 is to understand **who is on this team and what they each do.** Ask the user the questions in order. After each block, briefly summarize what they said back to confirm before moving on. Core Pass 1 questions: ``` Pass 1 — Team Identity 1. What is this project for? (one-sentence purpose, e.g., "Build and maintain the EZBI analytics platform" or "Generate marketing content for client campaigns") 2. What kind of team is this? - Software development - Marketing / creative - Real estate - Content / editorial - Sales / outreach - Customer success / support - Operations - Research - Other (describe it briefly) 3. What should this project be called? - Display name (e.g., "EZBI Platform") - Project ID (lowercase, hyphens or underscores, used in folder names — e.g., "ezbi") 4. Which agents will be on this team? (You can pick from your existing agents.) For each agent, what is their role on this project? (One agent might be "Project Manager" on this project and "Researcher" on another — the role is per-project.) 5. Which agent is client-facing? (Equivalent of a PM — receives requirements, talks to clients, owns the intake. There should be exactly one.) 6. Which agent validates feasibility? (Domain expert who reviews whether the work is doable before committing — e.g., engineer for dev work, strategist for marketing, broker for real estate.) 7. Which agent does quality review? (Reviews completed work before delivery to the client — e.g., QA for dev, creative director for marketing.) 8. Is there a human operator? (Final authority for merges, unresolvable escalations, client engagement when agents can't reach the client.) Yes / No — if yes, what's their alias? (e.g., "operator") 9. Are there any other roles? (Specialized contributors — designers, researchers, copywriters, etc.) ``` Record all answers. Confirm back before moving on. --- ## Step 3 — Pass 2: Work Structure Interview The goal of Pass 2 is to understand **how the team works together day-to-day.** ``` Pass 2 — Work Structure 1. Task manager — which one? - Asana - ClickUp (You should already have the corresponding dependency skill installed on your agents. Confirm which one.) 2. What are the stages a piece of work goes through? (These become the task manager columns. Default suggestion based on team type — confirm or customize.) 3. What is the shared working medium? - Where does this team actually produce deliverables? - Examples: a git repo (devs), a Google Drive folder (marketing), a Notion workspace (content), a CRM system (sales/real estate), a shared file folder, or none / not applicable - If a git repo: SSH URL(s) for cloning - If a folder/workspace: path or link - If a CRM/external system: how do agents access it? 4. What does "done" look like before work goes to client review? - Devs: PR opened, all tests pass, QA reviewed - Marketing: copy approved by creative director, brand guidelines met - Real estate: listing complete, photos verified, pricing confirmed - Whatever fits this team 5. How does the team handle requirements? - One sprint at a time (recommended): one agreed scope completed before next is accepted - Continuous flow: new requirements can come in any time (One-sprint-at-a-time is strongly recommended for teams that need focused execution. Continuous flow is appropriate for teams handling high-volume small tasks.) 6. Escalation thresholds: - How long should an agent be stuck on the same problem before stopping and surfacing to a human? (Default: 24 hours of active work) - How many times can an agent re-escalate the same issue before stopping? (Default: 2 escalations to the feasibility-reviewer) - How long with no client response before involving the operator? (Default: 48 hours) 7. Does this team produce or consume any visual / media assets? - Yes: describe (mockups, photos, video, audio, diagrams) - No (If yes: assets will be stored as task-manager attachments primarily, with a fallback location in the project workspace.) 8. Anything else specific to this team that other agents would need to know? (Free-form — house style, client communication preferences, specific tools/platforms, compliance requirements, etc.) ``` Record all answers. Confirm back before moving on. --- ## Step 4 — Pass 3: AI-Drafted Team Plan for Review This is the most important step. Take everything from Pass 1 and Pass 2 and produce a **comprehensive, operational team plan** — not a transcription of the user's answers, but an AI-rewritten, gap-filled version that any agent could read and immediately know how to operate. The plan must include: - **Team identity:** project name, ID, purpose, kind - **Roster:** every agent, their role on this project, what they own, what they do not own - **Task manager configuration:** which one, the column structure with each column's meaning - **Shared working medium:** what it is, how agents access it, conventions for using it - **Workflow phases:** every phase from intake through close, with who owns each, what triggers transitions - **Escalation rules:** thresholds, who escalates to whom, when work stops - **Communication protocol:** queue files between agents, who reads which queue - **Visual/media handling:** if applicable, how assets are stored and referenced - **What "done" means** at each phase - **Anything specific** the user mentioned Write this plan in clear, complete prose. Fill gaps the user didn't address explicitly — for example, if the user said "we have a designer" but didn't say what triggers the designer's involvement, infer reasonable defaults based on team type and write them in. Mark inferred items clearly so the user can correct them. Present the plan to the user: ``` I've turned your answers into a full team plan. Read through it carefully — this is what will go into PROJECT.md, which is what every agent on the team reads to understand how to operate. Items I inferred (not directly asked) are marked with [INFERRED]. Anything that doesn't match what you want, tell me and I'll revise. [FULL PLAN HERE] Does this match what you want? Anything to change before we build? ``` **Do not move to Step 5 until the user explicitly approves the plan.** This is the gate that prevents vague PROJECT.md files. Iterate as many times as needed. --- ## Step 5 — Capability Check Before building, look at the approved plan and check whether the assigned agents can actually do what the plan asks of them. Using openclaw-administrator, fetch each agent's configured model. Cross-reference against the plan: - **Vision required?** If the plan involves the agent reviewing mockups, photos, screenshots, or any visual asset, check that the agent's model has vision capability. If not, flag it. - **Long context required?** If the agent needs to read large documents (long specs, full codebases, large research corpora), check the model's context window. If under 200k and the work seems heavy, flag it. - **Code-heavy work?** If the agent is doing software development, check the model has reasonable coding benchmarks. (If the user picked something obviously weak, mention it.) - **Heartbeat model available?** Check whether the agent has OpenRouter configured (for `minimax-m2.7`) or at least one cheap model available for heartbeat use. If the agent's only model is a high-cost primary and there's no OpenRouter or cheap fallback, flag it — heartbeat on a primary model every 30 minutes is a significant credit burn. **Output format:** ``` Capability check on the assigned agents: ✅ [agent-id] (role: PM) — model [model-name] No concerns. ⚠️ [agent-id] (role: FE Designer) — model [model-name] Concern: This role will review visual mockups, but [model-name] does not support vision. Consider using a vision-capable model for tasks that involve images, or assigning that work to a different agent. ⚠️ [agent-id] (role: QA) — model [model-name] Concern: This model has a [X]% hallucination rate per public benchmarks, which is high for QA work that needs precise pass/fail judgment. This is advice — not a blocker. These are advisory only. You can proceed as-is, change agent models in your OpenClaw config, or reassign work to different agents. Proceed? (yes / make changes first) ``` Wait for the user. If they want to change agent models, that's their job — point them at openclaw-administrator. This skill does not set models. --- ## Step 6 — Task Manager Setup Based on the user's choice in Pass 2: ### If task manager board does NOT exist yet ``` Create the task manager board manually: 1. Log into [Asana / ClickUp] 2. Create a new project / space named: [project_display_name] 3. Set up the columns in this exact order: [column list from the approved plan] 4. Invite all agent accounts as members 5. Copy the project ID / GID from the board URL 6. Share the ID here when ready ``` ### Once the project ID is confirmed Using the task manager dependency skill (via the client-facing agent, since they own task creation), add a project description / pinned note with: ``` Project: [project_display_name] Project ID: [project-id] Client-facing agent: [agent-id] Feasibility reviewer: [agent-id] QA: [agent-id] Operator: [operator-alias or N/A] Shared workspace: [path or description] Task manager column meanings: [brief column legend] ``` Record the task manager project ID — it goes in `project.json`. --- ## Step 7 — Create Project Folder Structure This creates the entire project at `~/.openclaw/projects/[project-id]/`. Read `references/project-files.md` for the full specification of each file. ### Folder layout ``` ~/.openclaw/projects/[project-id]/ ├── PROJECT.md ← Team rulebook from the approved plan ├── project.json ← Machine-readable config ├── project-lock.json ← Phase tracker (initialized to "idle") ├── STATE.md ← Human-readable status ├── SHARED_MEMORY.md ← Cross-agent knowledge store ├── DECISIONS.md ← Append-only decision log ├── KNOWN_ISSUES.md ← Accepted limitations / debt ├── RUNBOOK.md ← Project operating guide (stub initially) ├── workspace/ │ ├── [shared medium] ← Repo, folder, files, depending on team │ ├── [media-folder/] ← Only if team uses visual/media assets │ ├── SPEC-CURRENT.md ← Current accepted spec / brief │ └── DELIVERABLES_GUIDE.md ← Feasibility-reviewer's task plan (was IMPLEMENTATION_GUIDE.md) └── queues/ ├── to-[client-facing-role].md ├── to-[feasibility-reviewer-role].md ├── to-[feasibility-reviewer-role]-feasibility.md ├── to-[qa-role].md ├── to-[operator].md ← Only if operator was specified └── to-[other-role].md ← One per other role on the team ``` ### Building each file **PROJECT.md** — generate from the PROJECT.md template in `references/templates.md`, filling every placeholder with the approved plan content from Step 4. This is the single most important file — it must be complete and operational. Use the placeholder reference table at the bottom of `references/templates.md` to map each placeholder to its source. **project.json** — generate from the project.json template in `references/templates.md`. Validate the result is valid JSON before writing. Fill in: - `id` and `name` from Pass 1 - `task_manager` block — type (asana / clickup), project ID, columns - `participants` — every agent with their project role and OpenClaw workspace path - `client_facing_role`, `feasibility_reviewer_role`, `qa_role`, `operator` — pointers to the right roles - `shared_workspace` and `shared_medium` — type and path/URL - `visual_assets` block — only if the team uses media (Pass 2 #7) - `queues` — file paths for each role's queue - `escalation_rules` — values from Pass 2 #6 **project-lock.json** — initialize: ```json { "phase": "idle", "sprint_id": null, "sprint_opened": null, "waiting_on": null, "last_updated": "[today]", "last_updated_by": "operator", "context": "Project initialized. Ready to receive first work.", "blocked_tasks": [] } ``` **STATE.md** — initialize: ```markdown # [project_display_name] — Current State **Phase:** Idle — Ready for first work **Last updated:** [today] by operator ``` **Queue files** — initialize each one with header: ``` # Queue: to-[role] # Format: [YYYY-MM-DD HH:MM] [FROM: agent-id] [TO: agent-id] [TASK: task-id or N/A] # Append-only. Never delete entries. Mark processed with [READ]. ``` **SHARED_MEMORY.md, DECISIONS.md, KNOWN_ISSUES.md** — each gets a header and an empty body. **RUNBOOK.md** — generate a stub with section headers appropriate for the team type, plus a note: ``` This is a starting stub. The feasibility-reviewer should expand each section as they learn the project. Devs / contributors read this before starting work. ``` **Shared medium initialization:** - Git repo: `cd ~/.openclaw/projects/[project-id]/workspace && git clone [ssh-url] [repo-name]` - Folder/Drive: create `workspace/[folder-name]/` and add a `LINKS.md` file with the external URL if not local - CRM/external: skip — write a `workspace/EXTERNAL_SYSTEM.md` describing where work happens - None: skip **Media folder** — only if Pass 2 #7 was yes: ```bash mkdir -p ~/.openclaw/projects/[project-id]/workspace/[media-folder-name] ``` --- ## Step 8 — Update Agent Workspaces For each participating agent, write two files: update their `AGENTS.md` with the project reference, and write their `HEARTBEAT.md` with direct queue lookup instructions. ### AGENTS.md — append Active Projects entry Append (or update) an Active Projects section in each agent's `AGENTS.md`: ```markdown ## Active Projects - **[project_display_name]** — I am the [role] on this project. - Full rules: ~/.openclaw/projects/[project-id]/PROJECT.md - My queue: ~/.openclaw/projects/[project-id]/queues/to-[my-role].md - Shared workspace: ~/.openclaw/projects/[project-id]/workspace/ - Check my queue at the start of every session before doing anything else. - Check ~/.openclaw/projects/[project-id]/project-lock.json to know what phase we are in before acting. ``` If the agent is already on other projects, **append** — do not overwrite. The agent should see all their active projects. ### HEARTBEAT.md — write per agent Write (or update) `HEARTBEAT.md` for each agent. The heartbeat model is: - `openrouter/minimax/minimax-m2.7` if OpenRouter is configured on this agent - Otherwise: the cheapest model in this agent's config (identify it now and fill it in below) Get the task manager section/column GID for each agent's queue from the task manager board confirmed in Step 6. If unavailable at setup time, leave the GID blank — the agent will discover it on first heartbeat and write it in. ```markdown /think:minimal # HEARTBEAT ## Task Manager Queue (read this, do not rediscover) - Project: [project_display_name] - Project ID / GID: [task_manager_project_id] - My Queue / Section: [Agent Role] Queue - Queue / Section GID: [section_gid_if_known] - Heartbeat model: [minimax-m2.7 via OpenRouter OR cheapest-available-model-id] ## On each heartbeat 1. Read the project ID and queue/section above — do not browse the task manager 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 in PROJECT.md. 6. If queue metadata above is missing or invalid → do one-time discovery, record the project ID 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 for any reason (tool error, bad model config, task manager 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. ``` If an agent participates in multiple projects, include a queue block per project in HEARTBEAT.md — one per project — and check each queue in sequence. --- ## Step 9 — Update OpenClaw Config Use openclaw-administrator to update each participating agent's `agent_to_agent` allow list so agents on this project can communicate. The allow list should include every other agent on the project. Be careful: if the agent is already on other projects, they may already have entries in their allow list for those project members. **Merge, don't replace.** Example: if agent `engineer` is on projects A and B: - Project A members: `pm-agent-a, dev-fe, dev-be, qa` - Project B members: `pm-agent-b, designer, copywriter, qa` - Final allow list for `engineer`: `pm-agent-a, dev-fe, dev-be, qa, pm-agent-b, designer, copywriter` After updating, verify: ``` openclaw agents list --verbose Confirm each agent's allow list includes all project members. ``` --- ## Step 10 — Smoke Test ``` SMOKE TEST Step 1: Manually create a test task in the [task-manager] [first-stage column]: Title: [TEST] Smoke test — verify [project-id] Description: Test task. The [client-facing role] agent should pick this up, acknowledge it, and either move it forward or post to a queue. Step 2: Wait for the [client-facing role] agent's next heartbeat (up to 30 min). Watch for: task gaining a comment, or moving to another column. Step 3: Confirm the agent is reading from the project folder. - Check [client-facing role] agent's session log - Should see references to ~/.openclaw/projects/[project-id]/PROJECT.md and the agent's queue file Step 4: Confirm queue files are writable. - Either: trigger a small interaction that produces a queue entry - Or: manually write a test entry to one queue file and verify the receiving agent picks it up next session Heartbeat confirmed working? (yes / no — describe what happened) ``` If something fails here, do not move to Step 11. Diagnose: - Agent didn't pick up task → check their AGENTS.md has the project reference, check their task manager skill is installed and authenticated - Agent picked up task but didn't write to queue → check `project-lock.json` is readable and `queues/` files exist with correct permissions - Agent-to-agent message didn't arrive → check OpenClaw config allow list from Step 9 --- ## Step 11 — Post-Setup Snapshot and Handoff ### Snapshot If openclaw-recovery-manager is installed: ``` Take post-setup snapshot. Label: post-project-setup-[project-id]-[date]-confirmed ``` ### Handoff Summary ``` PROJECT SETUP COMPLETE Project: [project_display_name] ([project-id]) Type: [team_type] Folder: ~/.openclaw/projects/[project-id]/ ROSTER: [role] | [agent-id] | [model] [client-facing role] | [agent-id] | [model] [feasibility role] | [agent-id] | [model] [qa role] | [agent-id] | [model] [operator] | human TASK MANAGER: Type: [Asana / ClickUp] Project ID: [id] Stages: [column list] SHARED WORKSPACE: [path or description] [Repo SSH URL if applicable] HOW TO START WORK: Send your first requirements / brief / intake to [client-facing-agent-id]. The team will: 1. Validate feasibility through [feasibility-reviewer] 2. Get your sign-off on the plan 3. Execute through [executing-roles] 4. Quality-review through [qa-role] 5. Notify [operator or you] when ready for sign-off ESCALATION: Stuck > [X]h or [Y] re-escalations → work stops, [operator] notified Client no response > [Z]h → [operator] gets a message ADD ANOTHER PROJECT: Run this skill again. Same agents can join multiple projects without conflict. RECOVERY: Pre-setup snapshot: pre-project-setup-[project-id]-[date] Post-setup snapshot: post-project-setup-[project-id]-[date]-confirmed ``` --- ## If Anything Goes Wrong ``` Option 1 — Recover using openclaw-recovery-manager: Restore: pre-project-setup-[project-id]-[date] Returns config to the state before setup began. Option 2 — Diagnose with openclaw-administrator: Run diagnostics, identify what failed, retry just that step. Option 3 — Describe what step failed and what error appeared. I can walk through the failed step again. ``` --- ## Adding Agents to an Existing Project Later If the user runs this skill against an existing project with the same project ID: 1. Detect the existing project folder 2. Ask: "Project [id] already exists. Are you adding agents, changing the structure, or something else?" 3. If adding agents: run only Pass 1 question 4 (agent assignment), check capabilities, update participants in `project.json`, append to AGENTS.md for new agents only, update allow lists in OpenClaw config 4. If changing structure: walk through the relevant interview sections, regenerate PROJECT.md, leave history files (DECISIONS.md, SHARED_MEMORY.md) intact Do not overwrite history files (DECISIONS.md, SHARED_MEMORY.md, queue archives) under any circumstance.

path: _meta.json
content: ownerId: kn77nfg6wv2expv6qs7k17dfqs83zp59
slug: openclaw-projects
version: 1.0.1
publishedAt: 1777270666545

path: references/templates.md
content: # Templates

Parameterized templates for files this skill generates. Read this when filling out
the project folder in Step 7 of SKILL.md. Substitute every `{{placeholder}}` with the
appropriate value from the user's interview answers and approved plan.

---

## Table of Contents

- [PROJECT.md Template](#projectmd-template)
- [project.json Template](#projectjson-template)
- [project-lock.json (Initial State)](#project-lockjson-initial-state)
- [STATE.md (Initial)](#statemd-initial)
- [Empty File Headers](#empty-file-headers)
- [AGENTS.md Active Projects Block](#agentsmd-active-projects-block)
- [Placeholder Reference](#placeholder-reference)

---

## PROJECT.md Template

The team rulebook. This is the single most important generated file — every agent
reads it. Fill in every placeholder, expand every conditional. If a section
doesn't apply (e.g. `{{#if visual_assets_enabled}}` is false), omit the entire
section rather than leaving an empty heading.

```markdown
# Project: {{project_display_name}}

**Project ID:** {{project_id}}
**Type:** {{team_type}}
**Purpose:** {{project_purpose}}

---

## The Team

{{#each participants}}
- **{{role}} ({{agentId}})** — {{role_description}}
{{/each}}
{{#if operator}}
- **Operator (Human, alias: {{operator}})** — Final authority. Sign-off, unresolvable escalations, client engagement when agents can't reach the client.
{{/if}}

---

## Source of Truth

| What | Where |
|---|---|
| Task ownership and status | {{task_manager_type}} |
| Accepted scope | `workspace/SPEC-CURRENT.md` |
| How to produce deliverables | `workspace/DELIVERABLES_GUIDE.md` |
| Cross-agent knowledge | `SHARED_MEMORY.md` |
| Decision history | `DECISIONS.md` |
| Accepted limitations | `KNOWN_ISSUES.md` |
| Project conventions | `RUNBOOK.md` |
| Current phase and ownership | `project-lock.json` |
| Human-readable status | `STATE.md` |

---

## Stages ({{task_manager_type}} Columns)

| Stage | Meaning | Owner |
|---|---|---|
{{#each stages}}
| {{name}} | {{purpose}} | {{owner}} |
{{/each}}

---

## Shared Working Medium

**Type:** {{shared_medium_type}}
**Location:** {{shared_medium_location}}

{{shared_medium_conventions}}

---

{{#if visual_assets_enabled}}
## Visual / Media Assets

When a task involves visual or media reference material:

- **Primary storage:** {{task_manager_type}} task attachments (retrieved via the installed {{task_manager_type}} skill)
- **Fallback storage:** `./workspace/{{media_folder_name}}/`
- **Naming convention:** `{{visual_naming_convention}}`
- **Task description must reference the asset filename** so executors and QA can locate it

**Vision-required roles:** {{vision_required_roles_list}}

These roles should use a vision-capable model when working with tasks that reference visual assets. If the asset cannot be retrieved from either source, treat it as a blocker and escalate per normal escalation rules.

---
{{/if}}

## Workflow

### Phase 1: Intake

**Owner:** {{client_facing_role}}
**Lock phase:** `intake`

1. {{client_facing_role}} receives or drafts {{intake_term}} from the client.
2. {{client_facing_role}} writes a draft to `workspace/SPEC-v[N]-[YYYY-MM-DD].md` (new version, never overwrite). Updates `SPEC-CURRENT.md`.
3. {{client_facing_role}} posts to `queues/to-{{feasibility_reviewer_role}}-feasibility.md`: "New scope draft ready for feasibility review."
4. {{feasibility_reviewer_role}} reviews for {{feasibility_concerns}}. Posts numbered issues back.
5. {{client_facing_role}} translates issues to client-friendly language. Sends to client via email skill or `to-{{operator}}.md` for relay.
6. Client responds to each numbered issue: Accept / Provide solution / Descope.
7. {{client_facing_role}} logs response in `DECISIONS.md` verbatim with date.
8. Loop until all issues resolved. {{feasibility_reviewer_role}} marks `SPEC-CURRENT.md` ACCEPTED.
9. `project-lock.json` → phase: `planning`.

**Client no-response rule:** No response in {{client_no_response_hours}}h → client-facing follows up. Still no response → posts to `to-{{operator}}.md`. Task moves to Blocked.

### Phase 2: Planning

**Owner:** {{feasibility_reviewer_role}}
**Lock phase:** `planning`

1. {{feasibility_reviewer_role}} writes `workspace/DELIVERABLES_GUIDE.md`. Each numbered section = one task.
2. Updates `KNOWN_ISSUES.md` with limitations accepted during intake.
3. Posts to `to-{{client_facing_role}}.md`: "Deliverables guide ready."
4. {{client_facing_role}} creates tasks in {{task_manager_type}} from guide, assigns to roles, places in {{first_stage_name}}.
5. `project-lock.json` → phase: `execution`, sprint_id set.

### Phase 3: Execution

**Owner:** Executors (per assigned task)
**Escalation owner:** {{feasibility_reviewer_role}}

1. Executor picks up task → moves to "In Progress" stage.
2. Reads DELIVERABLES_GUIDE.md, RUNBOOK.md, their queue.
{{#if visual_assets_enabled}}
3. If task references a visual asset and executor's role requires vision: switch to vision-capable model, retrieve asset.
{{/if}}
4. Produces deliverable in shared medium ({{shared_medium_type}}).
5. When complete: {{completion_action}}, move task to "In Review" stage, post to `to-{{qa_role}}.md`.

**Hard stop rule (universal):** If executor escalates same issue {{stuck_re_escalations_threshold}}x to reviewer OR is stuck {{stuck_hours_threshold}}h, executor stops. Posts full summary to `to-{{client_facing_role}}.md`. {{client_facing_role}} posts to `to-{{operator}}.md`. Task moves to Blocked. **No further AI cycles spent until operator resolves.**

### Phase 4: Review

**Owner:** {{qa_role}}

1. {{qa_role}} picks up task from "In Review" stage.
2. Reads KNOWN_ISSUES.md, SPEC-CURRENT.md, DELIVERABLES_GUIDE.md.
{{#if visual_assets_enabled}}
3. If deliverable includes visual output and task references a mockup: use vision to compare output to reference.
{{/if}}
4. Reviews against all references.

**Pass:** Move task to "Completed". Post to `to-{{operator}}.md` with deliverable pointer.
**Fail:** Post specific failures to `to-{{feasibility_reviewer_role}}.md`. Move task back to "In Progress".

{{#if operator}}
### Phase 5: {{operator}} Sign-off

1. {{operator}} reviews `to-{{operator}}.md`.
2. {{operator}} validates the deliverable (pulls/reviews/tests as appropriate for medium).
3. If satisfied: {{operator}} approves delivery via {{delivery_action}}.
4. `project-lock.json` → `phase: close`.
{{/if}}

### Phase 6: Close

**Owner:** {{client_facing_role}}

1. Verify all sprint tasks are "Completed" in {{task_manager_type}}.
2. Archive completed tasks.
3. Verify DECISIONS.md and KNOWN_ISSUES.md are current.
4. Write sprint summary to SHARED_MEMORY.md.
5. Update STATE.md: "Sprint [N] closed. Ready for next intake."
6. Archive queue entries (mark READ, do not delete).
7. `project-lock.json` → `phase: idle`.
8. Post to `to-{{operator}}.md`: "Sprint closed."

{{#if sprint_mode_one_at_a_time}}
**One sprint at a time:** {{client_facing_role}} does not accept new intake until project-lock.json is `idle`.
{{else}}
**Continuous flow:** {{client_facing_role}} can accept new intake at any time.
{{/if}}

---

## Escalation Rules

| Situation | Action | Threshold |
|---|---|---|
| Client not responding | {{client_facing_role}} follows up; then to operator | {{client_no_response_hours}}h |
| Executor stuck on task | Escalate to {{feasibility_reviewer_role}} | Immediately |
| Same issue re-escalated {{stuck_re_escalations_threshold}}x | Hard stop; client-facing → operator | {{stuck_re_escalations_threshold}} escalations |
| Executor stuck {{stuck_hours_threshold}}h | Hard stop; client-facing → operator | {{stuck_hours_threshold}}h |
| Task in Blocked with no movement | Client-facing → operator | {{blocked_task_operator_escalation_hours}}h |

**No agent continues spending AI cycles on a blocked path.**

---

## Communication Protocol

All inter-agent communication uses queue files in `queues/`.

**Format:**

    [YYYY-MM-DD HH:MM] [FROM: agent-id] [TO: agent-id] [TASK: task-id or N/A]
    Message body. Be specific.
    ---

- Queues are append-only. Never delete entries.
- Mark processed entries with `[READ]` — do not remove the line.
- Archive at sprint close.
- Each agent checks their queue at session start, before any other action.
- `to-{{feasibility_reviewer_role}}-feasibility.md` is used **only during intake phase**.

---

## Reference Block for Each Agent's AGENTS.md

Every participating agent's workspace AGENTS.md must include the block defined
in [AGENTS.md Active Projects Block](#agentsmd-active-projects-block) below.

{{#each user_specific_notes}}
---

## {{section_title}}

{{section_body}}
{{/each}}
```

---

## project.json Template

Machine-readable project config. Substitute every placeholder, then validate the
result is valid JSON before writing to disk.

```json
{
  "id": "{{project_id}}",
  "name": "{{project_display_name}}",
  "purpose": "{{project_purpose}}",
  "team_type": "{{team_type}}",
  "task_manager": {
    "type": "{{task_manager_type}}",
    "project_id": "{{task_manager_project_id}}",
    "columns": {
      "{{stage_key_1}}": { "id": "{{stage_id_1}}", "purpose": "{{stage_purpose_1}}" },
      "{{stage_key_2}}": { "id": "{{stage_id_2}}", "purpose": "{{stage_purpose_2}}" },
      "{{stage_key_3}}": { "id": "{{stage_id_3}}", "purpose": "{{stage_purpose_3}}" },
      "{{stage_key_4}}": { "id": "{{stage_id_4}}", "purpose": "{{stage_purpose_4}}" },
      "{{stage_key_5}}": { "id": "{{stage_id_5}}", "purpose": "{{stage_purpose_5}}" },
      "blocked": { "id": "{{blocked_stage_id}}", "purpose": "Work waiting on external resolution. Client-facing agent owns escalation." }
    }
  },
  "participants": [
    {
      "agentId": "{{participant_agent_id}}",
      "workspace": "{{participant_workspace_path}}",
      "role": "{{participant_role_display}}",
      "role_key": "{{participant_role_key}}"
    }
  ],
  "client_facing_role": "{{client_facing_role_key}}",
  "feasibility_reviewer_role": "{{feasibility_reviewer_role_key}}",
  "qa_role": "{{qa_role_key}}",
  "operator": "{{operator_alias_or_null}}",
  "shared_workspace": "./workspace",
  "shared_medium": {
    "type": "{{shared_medium_type}}",
    "path_or_url": "{{shared_medium_location}}",
    "convention_notes": "{{shared_medium_conventions}}"
  },
  "spec_path": "./workspace/SPEC-CURRENT.md",
  "deliverables_guide_path": "./workspace/DELIVERABLES_GUIDE.md",
  "shared_memory": "./SHARED_MEMORY.md",
  "decisions_log": "./DECISIONS.md",
  "known_issues": "./KNOWN_ISSUES.md",
  "runbook": "./RUNBOOK.md",
  "queues": {
    "{{client_facing_role_key}}": "./queues/to-{{client_facing_role_key}}.md",
    "{{feasibility_reviewer_role_key}}": "./queues/to-{{feasibility_reviewer_role_key}}.md",
    "{{feasibility_reviewer_role_key}}_feasibility": "./queues/to-{{feasibility_reviewer_role_key}}-feasibility.md",
    "{{qa_role_key}}": "./queues/to-{{qa_role_key}}.md",
    "operator": "./queues/to-{{operator_alias_or_null}}.md"
  },
  "visual_assets": {
    "enabled": false,
    "primary_storage": "task_manager_attachments",
    "fallback_storage": "./workspace/{{media_folder_name}}",
    "naming_convention": "[task-id]-[short-description].[ext]",
    "vision_required_roles": []
  },
  "escalation_rules": {
    "client_no_response_hours": 48,
    "stuck_re_escalations_threshold": 2,
    "stuck_hours_threshold": 24,
    "blocked_task_operator_escalation_hours": 48
  },
  "sprint_mode": "one_at_a_time"
}
```

If `visual_assets.enabled` is set to `true`, populate `vision_required_roles` with
the role keys that need vision capability. Set `fallback_storage` to the actual
media folder path the skill creates in `workspace/`.

If there is no operator, set `"operator": null` (without quotes) and **omit the
`"operator"` key from the `queues` block entirely** rather than leaving it
pointing at a queue file that won't exist.

---

## project-lock.json (Initial State)

Initialize fresh on every project creation:

```json
{
  "phase": "idle",
  "sprint_id": null,
  "sprint_opened": null,
  "waiting_on": null,
  "last_updated": "{{today_iso_date}}",
  "last_updated_by": "operator",
  "context": "Project initialized. Ready to receive first work.",
  "blocked_tasks": []
}
```

---

## STATE.md (Initial)

Initialize fresh on every project creation:

```markdown
# {{project_display_name}} — Current State
**Phase:** Idle — Ready for first work
**Last updated:** {{today_iso_date}} by operator
```

---

## Empty File Headers

Use these for the files that start empty but need a header so agents know what
they are.

### SHARED_MEMORY.md

```markdown
# {{project_display_name}} — Shared Memory

Cross-agent knowledge that needs to persist across sessions but doesn't belong
in the task manager. Append entries with date and author.

Format for new entries:

    ## [YYYY-MM-DD] [agent-id] — [topic]
    Content here.
    ---
```

### DECISIONS.md

```markdown
# {{project_display_name}} — Decision Log

Append-only record of every significant decision made during intake or scope
negotiation. Never edit existing entries. Written by {{client_facing_role}}.

Format for new entries:

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

    **Issue surfaced by [feasibility reviewer]:** ...

    **Client response (received [date]):** ...

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

    **Accepted by:** [Client name], [feasibility reviewer agent], [client-facing agent]
    **Logged by:** [client-facing agent]
    ---
```

### KNOWN_ISSUES.md

```markdown
# {{project_display_name}} — Known Issues

Accepted limitations and trade-offs. QA reads this before reviewing — do not
file failures against items here. Written by {{feasibility_reviewer_role}}.

Format for new entries:

    ## [Sprint ID] — [Issue Title]
    - **Accepted:** [date]
    - **Context:** [why this limitation exists]
    - **Impact:** [what users/clients/operators will experience]
    ---
```

### RUNBOOK.md (stub)

```markdown
# {{project_display_name}} — Runbook

This is a starting stub. The {{feasibility_reviewer_role}} should expand each
section as they learn the project. All agents read this before starting work.

## Local Setup / Access

How to access the shared working medium ({{shared_medium_type}}).

## Conventions

How this team formats work, names things, and structures deliverables.

## Definition of Done

What counts as complete on this project.

## Known Gotchas

Pitfalls specific to this project — things that have tripped up agents before.

{{#each team_type_specific_sections}}
## {{section_title}}

{{section_body_or_placeholder}}
{{/each}}
```

### Queue Files

Initialize each queue file with:

```markdown
# Queue: to-{{role_key}}

Format for entries:

    [YYYY-MM-DD HH:MM] [FROM: agent-id] [TO: agent-id] [TASK: task-id or N/A]
    Message body. Be specific.
    ---

Append-only. Never delete entries. Mark processed entries with [READ] prepended.
Archive at sprint close (mark READ, leave in place).
```

---

## AGENTS.md Active Projects Block

Insert (or append) this block in each participating agent's workspace AGENTS.md.
If the agent is already on other projects, append — never overwrite.

```markdown
## Active Projects

- **{{project_display_name}}** — I am the {{my_role}} on this project.
  - Full rules: ~/.openclaw/projects/{{project_id}}/PROJECT.md
  - My queue: ~/.openclaw/projects/{{project_id}}/queues/to-{{my_role_key}}.md
  - Shared workspace: ~/.openclaw/projects/{{project_id}}/workspace/
  - Check my queue at the start of every session before doing anything else.
  - Check ~/.openclaw/projects/{{project_id}}/project-lock.json to know what
    phase we are in before acting.
```

---

## Placeholder Reference

Every placeholder used across the templates above. Source column tells you
where the value comes from.

| Placeholder | Source |
|---|---|
| `{{project_id}}` | Pass 1 #3 |
| `{{project_display_name}}` | Pass 1 #3 |
| `{{project_purpose}}` | Pass 1 #1 |
| `{{team_type}}` | Pass 1 #2 |
| `{{participants}}` (list) | Pass 1 #4 — each entry has `agentId`, `role`, `role_key`, `role_description`, `workspace` |
| `{{operator}}` | Pass 1 #8 (alias) or null |
| `{{client_facing_role}}` | Pass 1 #5 (display name) |
| `{{client_facing_role_key}}` | Pass 1 #5 (slug form) |
| `{{feasibility_reviewer_role}}` | Pass 1 #6 (display name) |
| `{{feasibility_reviewer_role_key}}` | Pass 1 #6 (slug) |
| `{{qa_role}}` | Pass 1 #7 (display name) |
| `{{qa_role_key}}` | Pass 1 #7 (slug) |
| `{{task_manager_type}}` | Pass 2 #1 — `asana` or `clickup` |
| `{{task_manager_project_id}}` | From Step 6 (after board creation) |
| `{{stages}}` (list) | Pass 2 #2 — each has `name`, `key`, `id`, `purpose`, `owner` |
| `{{first_stage_name}}` | Pass 2 #2 (first column) |
| `{{shared_medium_type}}` | Pass 2 #3 — `git`, `folder`, `external_system`, or `none` |
| `{{shared_medium_location}}` | Pass 2 #3 |
| `{{shared_medium_conventions}}` | Inferred in Step 4, user-confirmed |
| `{{visual_assets_enabled}}` | Pass 2 #7 (boolean) |
| `{{media_folder_name}}` | Inferred from team type — e.g. `mockups`, `photos`, `media` |
| `{{visual_naming_convention}}` | Default: `[task-id]-[short-description].[ext]` |
| `{{vision_required_roles_list}}` | Inferred in Step 4 from team type |
| `{{intake_term}}` | Per team type — e.g. "requirements", "brief", "lead" |
| `{{feasibility_concerns}}` | Per team type — see team-archetypes.md |
| `{{completion_action}}` | Per team type — e.g. "push to sprint branch and update PR" |
| `{{delivery_action}}` | Per team type — e.g. "merge to main", "send to client", "publish to MLS" |
| `{{sprint_mode_one_at_a_time}}` | Pass 2 #5 (boolean) |
| `{{client_no_response_hours}}` | Pass 2 #6 (default 48) |
| `{{stuck_hours_threshold}}` | Pass 2 #6 (default 24) |
| `{{stuck_re_escalations_threshold}}` | Pass 2 #6 (default 2) |
| `{{blocked_task_operator_escalation_hours}}` | Default 48 |
| `{{user_specific_notes}}` | Pass 2 #8 (free-form additions) |
| `{{today_iso_date}}` | Today's date in YYYY-MM-DD |
| `{{my_role}}` / `{{my_role_key}}` | Per-agent when generating their AGENTS.md block |


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

Full specification of every file in `~/.openclaw/projects/[project-id]/`.
Universal — applies to any team type.

---

## Table of Contents

- [PROJECT.md — Team Rulebook](#projectmd--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 Operating Guide](#runbookmd--project-operating-guide)
- [workspace/SPEC-CURRENT.md](#workspacespec-currentmd)
- [workspace/DELIVERABLES_GUIDE.md](#workspacedeliverables_guidemd)
- [Queue Files](#queue-files)
- [File Responsibility Matrix](#file-responsibility-matrix)

---

## PROJECT.md — Team Rulebook

**The most important file in the project folder.** Every participating agent has this referenced from their AGENTS.md and reads it before taking action. It is the single source of truth for how the team operates on this project.

### Who reads it
All agents on the project, at every session start.

### Who writes it
Generated by this skill from the user's interview answers (after Step 4 approval). Updated by operator only when workflow rules change.

### Required sections

A complete PROJECT.md must contain:

1. **Project header** — display name, ID, purpose, team type
2. **The Team** — every agent on the project, their role, what they own and do not own
3. **Source of Truth** — table mapping "what" to "where"
4. **Stages** (task manager columns) — name, meaning, who owns it
5. **Shared Working Medium** — what it is, how to access, conventions for use
6. **Visual / Media Assets** — only if applicable: storage convention, vision-required roles
7. **Workflow** — every phase from intake to close, with steps, owners, and queue references
8. **Escalation Rules** — thresholds, who escalates to whom, when work stops
9. **Communication Protocol** — queue file format, when to check, append-only rules
10. **AGENTS.md Reference Block** — the snippet that goes in each agent's AGENTS.md

See the PROJECT.md template in `references/templates.md` for the parameterized template.

---

## project.json — Machine Config

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

### Who reads it
All agents.

### Who writes it
Generated by this skill. Updated by operator when project structure changes.

### Schema

```json
{
  "id": "string — lowercase project identifier",
  "name": "string — display name",
  "purpose": "string — one-line description of project goal",
  "team_type": "string — software_dev | marketing | real_estate | content | sales | customer_success | operations | research | custom",
  "task_manager": {
    "type": "asana | clickup",
    "project_id": "string — task manager's project/workspace ID",
    "columns": {
      "stage_key": { "id": "string", "purpose": "string" }
    }
  },
  "participants": [
    {
      "agentId": "string",
      "workspace": "string — relative path to agent's OpenClaw workspace",
      "role": "string — display name (e.g. 'Project Manager')",
      "role_key": "string — machine slug (e.g. 'pm')"
    }
  ],
  "client_facing_role": "string — role_key of client-facing agent",
  "feasibility_reviewer_role": "string — role_key",
  "qa_role": "string — role_key",
  "operator": "string — operator alias, or null if no operator",
  "shared_workspace": "./workspace",
  "shared_medium": {
    "type": "git | folder | external_system | none",
    "path_or_url": "string — local path or external URL",
    "convention_notes": "string — brief notes on usage"
  },
  "spec_path": "./workspace/SPEC-CURRENT.md",
  "deliverables_guide_path": "./workspace/DELIVERABLES_GUIDE.md",
  "shared_memory": "./SHARED_MEMORY.md",
  "decisions_log": "./DECISIONS.md",
  "known_issues": "./KNOWN_ISSUES.md",
  "runbook": "./RUNBOOK.md",
  "queues": {
    "role_key": "string — relative path to queue file"
  },
  "visual_assets": {
    "enabled": "boolean",
    "primary_storage": "task_manager_attachments | workspace_folder | none",
    "fallback_storage": "string — relative path to media folder, or null",
    "naming_convention": "string — e.g. '[task-id]-[short-description].[ext]'",
    "vision_required_roles": ["array of role_keys"]
  },
  "escalation_rules": {
    "client_no_response_hours": "number",
    "stuck_re_escalations_threshold": "number",
    "stuck_hours_threshold": "number",
    "blocked_task_operator_escalation_hours": "number"
  },
  "sprint_mode": "one_at_a_time | continuous"
}
```

### Notes
- All file paths use relative paths from project root
- Task manager column IDs must be filled in from the actual board after creation
- `visual_assets.enabled: false` if the team doesn't use media — the entire block can still be present, just disabled
- `operator: null` for fully autonomous teams (rare)

---

## 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 any action.

### Who writes it
Client-facing agent (most phase transitions), feasibility-reviewer (planning → execution), QA (after sign-off), operator (close → idle).

### Phase progression
`idle` → `intake` → `planning` → `execution` → `review` → `close` → `idle`

These phase names replace the dev-specific names. Translation:
- `intake` = formerly "requirements" (universal: receiving and validating new work)
- `planning` = same (defining how the work gets done)
- `execution` = formerly "implementation" (universal: doing the work)
- `review` = formerly "qa" (universal: quality review before delivery)
- `close` = formerly "sprint-close" (universal: wrap up and reset)

### Format

```json
{
  "phase": "string — one of the phase names above",
  "sprint_id": "string or null",
  "sprint_opened": "string ISO date or null",
  "waiting_on": "string agent-id, 'client', 'operator', or null",
  "last_updated": "string ISO date",
  "last_updated_by": "string — agent-id or 'operator'",
  "context": "string — human-readable description of current state",
  "blocked_tasks": ["array of task identifiers"]
}
```

### Agent behavior rules
- Phase doesn't match my expected action → stop and post to relevant queue
- `waiting_on` is me → act immediately
- `blocked_tasks` contains my task → treat as stopped, do not work on it

---

## STATE.md — Human Status

Operator's quick-glance status without digging through queues or task manager.

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

### Who writes it
All agents update 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 / Work in Flight
- ✅ [Task ID] — [description] (delivered)
- 🔄 [Task ID] — [description] (in progress, [agent])
- ⏳ [Task ID] — [description] (queued)
- 🚫 [Task ID] — [description] (blocked — [reason])

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

---

## SHARED_MEMORY.md — Cross-Agent Knowledge

Living document for project knowledge that persists across sessions but doesn't belong in the task manager.

### What goes here (universal)
- Domain knowledge agents have learned about this project
- Client preferences and communication style
- Conventions specific to this client or this work
- Cross-sprint summaries (added by client-facing agent at close)
- Anything one agent needs to tell another that doesn't fit a task

### What does NOT go here
- Task status → task manager
- Accepted scope → SPEC files
- How-to-do-the-work → DELIVERABLES_GUIDE.md
- Decisions and acceptances → DECISIONS.md
- Limitations → KNOWN_ISSUES.md

### Format
```markdown
## [YYYY-MM-DD] [agent-id] — [topic]
Content here.
---
```

---

## DECISIONS.md — Decision Log

**Append-only.** Every significant decision made during intake or scope negotiation. Never edit existing entries.

### Who reads it
Client-facing agent, feasibility reviewer, operator. QA references when filing failures.

### Who writes it
Client-facing agent, during intake phase as decisions are made.

### Purpose
When a client later disputes what was agreed, this is the record. It captures what was proposed, what issue was surfaced, what the client said, what was accepted.

### Format

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

**Issue surfaced by [feasibility reviewer]:** [description of the issue, options if any]

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

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

**Accepted by:** [Client name], [feasibility reviewer agent], [client-facing agent]
**Logged by:** [client-facing agent]
---
```

---

## KNOWN_ISSUES.md — Accepted Limitations

Accepted limitations and trade-offs. QA reads before reviewing — does not file failures against items here.

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

### Who writes it
Feasibility reviewer, during planning and as new limitations are accepted.

### Format

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

---

## RUNBOOK.md — Project Operating Guide

Maintained by feasibility reviewer. All contributors read before starting work to avoid unnecessary escalations.

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

### Who writes it
Initial stub generated by this skill (with section headers appropriate for team type). Feasibility reviewer fills in details after first session with the project.

### Universal sections (always present)
- Local Setup / Access — how to access the shared medium
- Conventions — how the team formats work, names things, etc.
- Definition of Done — what counts as complete
- Known Gotchas — pitfalls specific to this project

### Team-type-specific sections
See `references/team-archetypes.md` for sections appropriate to each team type.

---

## workspace/SPEC-CURRENT.md

Reference to the currently active accepted specification / brief / scope document.

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

### Status markers
Feasibility reviewer adds one when reviewing:
```
STATUS: DRAFT — Under feasibility review
STATUS: ACCEPTED — [date] — [feasibility-reviewer-agent] + [client-facing-agent]
```

---

## workspace/DELIVERABLES_GUIDE.md

Written by feasibility reviewer after spec is accepted. Task-oriented blueprint for what gets produced and how.

This file replaces the dev-specific "IMPLEMENTATION_GUIDE.md" with a universal name. It serves the same function across all team types: turn the accepted scope into discrete tasks the executors can work on.

### Format

```markdown
# Deliverables Guide — [Sprint ID]

## Task 1: [Task Title]
**Assigned to:** [role / agent]
**Task manager ID:** [created by client-facing agent after this guide is written]

### What to produce
[Description of the deliverable]

### Inputs / dependencies
[What this task depends on or requires]

### Approach
[How to do it — high-level. Not full execution.]

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

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

## Task 2: ...
```

---

## Queue Files

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

Standard set:
- `to-[client-facing-role].md`
- `to-[feasibility-reviewer-role].md`
- `to-[feasibility-reviewer-role]-feasibility.md` (intake phase only — separate from execution escalations)
- `to-[qa-role].md`
- `to-[operator].md` (only if operator exists)
- `to-[other-role].md` for each additional role

### Format (universal — every entry must use this)

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

### Rules (universal)
- Append-only — never delete entries
- Mark processed entries by prepending `[READ]` — 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
- Feasibility queue is **only** used during intake phase — keeps it separate from execution escalations

---

## File Responsibility Matrix

| File | Created by | Updated by | Read by | Mutability |
|---|---|---|---|---|
| `PROJECT.md` | This skill | Operator | All agents | Rare (workflow changes only) |
| `project.json` | This skill | Operator | All agents | Structure changes only |
| `project-lock.json` | This skill | All agents (per phase) | All agents | Every phase change |
| `STATE.md` | This skill | All agents | Operator, all agents | Frequently |
| `SHARED_MEMORY.md` | This skill | All agents (append) | All agents | Frequently |
| `DECISIONS.md` | This skill | Client-facing agent (append) | Client-facing, feasibility, operator | Append-only |
| `KNOWN_ISSUES.md` | This skill | Feasibility reviewer (append) | QA, all agents | Append-only |
| `RUNBOOK.md` | This skill (stub) | Feasibility reviewer | All agents | As patterns evolve |
| `SPEC-vN-*.md` | Client-facing agent | Never | Client-facing, feasibility | Immutable |
| `SPEC-CURRENT.md` | Client-facing agent | Client-facing (per sprint) | All agents | Per sprint |
| `DELIVERABLES_GUIDE.md` | Feasibility reviewer | Feasibility reviewer | All executors, QA | Per sprint |
| `queues/to-*.md` | This skill (init) | Named sender (append) | Named recipient | Append-only |


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

Universal workflow for any project type managed under OpenClaw Projects. Read this when:
- Drafting the workflow section of PROJECT.md in Step 4
- Troubleshooting agent behavior during a sprint
- Explaining how the team should operate

---

## Table of Contents

- [Phase Overview](#phase-overview)
- [Phase 1: Intake](#phase-1-intake)
- [Phase 2: Planning](#phase-2-planning)
- [Phase 3: Execution](#phase-3-execution)
- [Phase 4: Review](#phase-4-review)
- [Phase 5: Operator Sign-off](#phase-5-operator-sign-off)
- [Phase 6: Close](#phase-6-close)
- [Escalation Rules](#escalation-rules)
- [Queue Message Format](#queue-message-format)
- [Agent Session Start Checklist](#agent-session-start-checklist)

---

## Phase Overview

```
idle → intake → planning → execution → close → idle
                                ↕
                              review
```

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

The phase names are universal across team types. The *content* of each phase is team-specific (see `references/team-archetypes.md`), but the structure is the same.

---

## Phase 1: Intake

**Owner:** Client-facing agent
**Lock phase:** `intake`
**Queue used:** `to-[feasibility-reviewer]-feasibility.md`

### Steps

1. Client-facing agent receives or drafts work intake (requirements, brief, request, lead — whatever the team type).
2. Client-facing agent creates a versioned spec file: `workspace/SPEC-v[N]-[YYYY-MM-DD].md`
   - Never overwrite — always increment version
   - Updates `SPEC-CURRENT.md` to reference this draft
   - Marks file: `STATUS: DRAFT — Under feasibility review`
3. Client-facing agent posts to feasibility queue:
   ```
   [date] [FROM: client-facing] [TO: feasibility-reviewer]
   New scope draft ready for feasibility review.
   File: workspace/SPEC-v[N]-[YYYY-MM-DD].md
   ---
   ```
4. Feasibility reviewer reads spec and reviews for the team-specific concerns. Examples:
   - **Software dev:** technical feasibility, architecture conflicts, ambiguities
   - **Marketing:** brand fit, channel feasibility, budget alignment
   - **Real estate:** pricing realism, market fit, compliance
   - **Whatever fits the team**
5. Reviewer posts numbered issues to feasibility queue:
   ```
   [date] [FROM: feasibility-reviewer] [TO: client-facing]
   Feasibility review complete. [N] issues to resolve before accepting.

   Issue 1: [title]
   [description, concrete impact, options if available]

   Issue 2: ...
   ---
   ```
6. Client-facing agent translates issues into client-friendly language and sends to client (via email skill if available, or via `to-operator.md` if not).
7. Client responds to each numbered issue:
   - **Accept as known outcome**
   - **Provide a solution** for reviewer to evaluate
   - **Descope** — remove the requirement
8. Client-facing agent logs response in `DECISIONS.md` with date.
9. If client proposes solution, reviewer evaluates. Loop repeats until all issues resolved.
10. When resolved:
    - Reviewer updates `SPEC-CURRENT.md`: `STATUS: ACCEPTED — [date] — [reviewer] + [client-facing]`
    - Client-facing agent logs final acceptance in `DECISIONS.md`
    - Client-facing agent updates `project-lock.json` → `phase: planning`

### Client No-Response Rule
- No response in [client_no_response_hours] → client-facing agent sends follow-up
- Still no response → client-facing agent posts to `to-operator.md`:
  ```
  [date] [FROM: client-facing] [TO: operator]
  Client has not responded to feasibility issues for [hours]h. Follow-up sent.
  Please engage client directly. Issues are in queues/to-[feasibility]-feasibility.md.
  ---
  ```
- Task moves to "Blocked" stage in task manager

---

## Phase 2: Planning

**Owner:** Feasibility reviewer
**Lock phase:** `planning`

### Steps

1. Reviewer writes `workspace/DELIVERABLES_GUIDE.md`:
   - Each numbered section = one task in the task manager
   - Detailed enough to execute without ambiguity
   - Approach-level, not full execution
   - References `KNOWN_ISSUES.md` items created from this guide
   - **If scope includes visual/media assets:** reviewer uses vision capability (if model supports it) to review them. Each task referencing a visual asset must include the asset filename so executors and QA can locate it.
2. Reviewer updates `KNOWN_ISSUES.md` with limitations accepted during intake.
3. Reviewer posts to client-facing agent's queue:
   ```
   [date] [FROM: feasibility-reviewer] [TO: client-facing]
   Deliverables guide ready. workspace/DELIVERABLES_GUIDE.md
   [N] tasks defined.
   ---
   ```
4. Client-facing agent reviews guide for completeness.
5. Client-facing agent creates tasks in task manager from guide:
   - One task per numbered section
   - Task description includes the relevant guide section
   - Tasks placed in first stage (Backlog or equivalent), assigned to appropriate roles
6. Client-facing agent posts to feasibility-reviewer's queue:
   ```
   [date] [FROM: client-facing] [TO: feasibility-reviewer]
   Sprint [N] open. [X] tasks created.
   ---
   ```
7. Client-facing agent updates `project-lock.json`:
   ```json
   {
     "phase": "execution",
     "sprint_id": "sprint-[N]",
     "sprint_opened": "[date]"
   }
   ```
8. Client-facing agent updates `STATE.md`.

---

## Phase 3: Execution

**Owner:** Executors (their assigned tasks)
**Escalation owner:** Feasibility reviewer
**Lock phase:** `execution`

### Executor Task Flow

1. Executor picks up assigned task → moves to "In Progress" stage in task manager.
2. Executor reads:
   - `workspace/DELIVERABLES_GUIDE.md` — relevant task section
   - `RUNBOOK.md` — project conventions
   - Their queue — pending messages
3. **If task references a visual/media asset:**
   - Executor switches to vision-capable model (if their config supports it)
   - Retrieves asset from task manager attachment (preferred) or workspace media folder
   - If asset cannot be retrieved → blocker, escalate to feasibility reviewer
4. Executor produces the deliverable in the shared working medium.
5. When complete:
   - **Software dev:** push to sprint branch; first task opens PR, subsequent push updates PR
   - **Marketing/content:** save to shared drive in approved location
   - **Real estate:** update CRM with completion details
   - **Whatever fits the medium**
   - Move task from "In Progress" → "In Review" stage
   - Post to QA's queue:
     ```
     [date] [FROM: executor] [TO: qa] [TASK: task-id]
     Task [id] complete. [Pointer to deliverable — PR URL, file path, etc.]
     What was produced: [brief description]
     ---
     ```
6. Executor moves to next task if available.

### Executor Escalation Rules

**When blocked:**
- Post to feasibility reviewer's queue with task ID, what was tried, specific question
- Reviewer responds in executor's queue
- Executor waits for response

**Hard stop rule — triggers when EITHER condition is met:**
- Same issue escalated [stuck_re_escalations_threshold] times to reviewer without resolution, OR
- Executor stuck on same issue for [stuck_hours_threshold] hours

**When hard stop triggers:**
1. Executor stops work on that task immediately
2. Executor posts full summary to client-facing agent's queue:
   ```
   [date] [FROM: executor] [TO: client-facing] [TASK: task-id]
   HARD STOP — escalation limit reached.
   Issue: [description]
   Escalation history:
     [date] — First escalation: [question]
     [date] — Reviewer response: [response]
     [date] — Second escalation: [question]
     [date] — Reviewer response: [response]
   Still blocked because: [reason]
   Awaiting operator assistance before resuming.
   ---
   ```
3. Task moves to "Blocked" in task manager
4. Client-facing agent posts to `to-operator.md`
5. **No further AI cycles spent on this task until operator resolves**

---

## Phase 4: Review

**Owner:** QA reviewer
**Lock phase:** `execution` (review runs concurrently with ongoing execution)

### QA Flow

1. QA picks up task from "In Review" stage → moves to "QA" or "Review" stage.
2. QA reads:
   - `KNOWN_ISSUES.md` — do not file failures against accepted limitations
   - `workspace/SPEC-CURRENT.md` — accepted scope
   - `workspace/DELIVERABLES_GUIDE.md` — planned approach for this task
3. **If deliverable includes visual output and task references a mockup:**
   - QA uses vision (if model supports) to compare output to reference
   - Visual deviations not in `KNOWN_ISSUES.md` are failures
4. QA reviews deliverable against all references.

### QA Pass
```
[date] [FROM: qa] [TO: operator] [TASK: task-id]
Task [id] — REVIEW PASSED.
Deliverable: [pointer]
Verified against: SPEC-CURRENT.md + DELIVERABLES_GUIDE.md task [N]
No known issues flagged.
---
```
- Move task to "Completed" stage

### QA Fail
```
[date] [FROM: qa] [TO: feasibility-reviewer] [TASK: task-id]
Task [id] — REVIEW FAILED. [N] issues found.

Issue 1: [specific — what was checked, what was expected, what happened]
Issue 2: ...
---
```
- Move task back to "In Progress"
- Executor addresses failures and re-submits
- QA re-reviews

---

## Phase 5: Operator Sign-off

**Owner:** Operator (human, if defined)
**Lock phase:** `close` (after sign-off)

### Flow

1. Operator reviews `to-operator.md` for QA-passed tasks.
2. Operator validates the deliverable:
   - **Software dev:** pull branch, review, test
   - **Marketing/content:** read the deliverable
   - **Real estate:** verify listing data
   - **Whatever fits**
3. If satisfied:
   - **Software dev:** tells QA to merge to main; rebases other repos
   - **Other:** approves delivery to client through whatever channel applies
4. Operator updates `project-lock.json` → `phase: close`.

### If no operator (rare)
QA's pass message is the sign-off. Move directly to close phase.

---

## Phase 6: Close

**Owner:** Client-facing agent
**Lock phase:** `idle` (after close)

### Close Checklist

1. Verify all sprint tasks are in "Completed" stage in task manager.
2. Archive completed tasks (close/archive — do not delete).
3. Verify `DECISIONS.md` has complete record for this sprint.
4. Verify `KNOWN_ISSUES.md` is current.
5. Write sprint summary to `SHARED_MEMORY.md`:
   ```markdown
   ## [date] Sprint [N] Close — [client-facing-agent]
   What was delivered: [summary]
   Issues accepted: [reference to KNOWN_ISSUES entries]
   Client sign-off: [yes/no — how confirmed]
   Carry-over notes: [anything for next sprint]
   ```
6. Update `STATE.md`:
   ```markdown
   # [Project Name] — Current State
   **Phase:** Idle — Sprint [N] closed. Ready for next intake.
   ```
7. Archive queue entries (mark `[READ]`, do not delete).
8. Update `project-lock.json`:
   ```json
   {
     "phase": "idle",
     "sprint_id": null,
     "sprint_opened": null,
     "waiting_on": null,
     "context": "Sprint [N] closed. Ready for next intake."
   }
   ```
9. Post to operator's queue: "Sprint [N] closed. Ready for next intake."

**One sprint at a time mode:** Client-facing agent does not accept new intake until `project-lock.json` is `idle`.

**Continuous flow mode:** Client-facing agent can accept new intake immediately. Each piece of work flows through phases independently. Sprint close still happens for periodic cleanup, but new intake doesn't wait for it.

---

## Escalation Rules

| Situation | Action | Threshold |
|---|---|---|
| Client not responding to scope | Client-facing follows up; then escalates to operator | client_no_response_hours |
| Executor blocked on task | Escalate to feasibility reviewer | Immediately when blocked |
| Same issue re-escalated to reviewer | Hard stop; client-facing escalates to operator | stuck_re_escalations_threshold |
| Executor stuck same issue | Hard stop; client-facing escalates to operator | stuck_hours_threshold |
| Task in Blocked with no movement | Client-facing escalates to operator | blocked_task_operator_escalation_hours |
| QA failing same task repeatedly | QA posts to reviewer; client-facing monitors | — |

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

---

## Queue Message Format

Every queue entry must use this exact format:

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

### Rules
- Queues are append-only — never delete entries
- Mark processed entries by prepending `[READ]` — do not remove the line
- Archive at sprint close (mark READ, leave in place)
- Each agent checks their queue at session start, before any other action
- Feasibility queue is **only** used during intake phase

---

## Agent Session Start Checklist

Every agent runs this at the start of every session:

1. Read `project-lock.json` for each project they're on — what phase is each in?
2. Read `queues/to-[my-role].md` for each project — any pending messages?
3. If unread queue messages exist, address them before starting new work
4. If phase doesn't match my expected action, post to relevant queue and wait
5. If phase matches and no pending messages, proceed with current task

**Queue and phase check always come before anything else.**


path: references/team-archetypes.md
content: # Team Archetypes

Reference patterns for common team types. Read this when:
- Drafting the team plan in Step 4 and need a reference example
- The user's team is novel and you're inferring conventions
- Writing the RUNBOOK.md stub and need section ideas

These are starting points, not prescriptions. Every team adapts the pattern.

---

## Software Development Team

**Roles:**
- **PM (client-facing)** — receives feature requests, manages scope, talks to client
- **Engineer (feasibility reviewer)** — reviews technical feasibility, writes implementation guides
- **FE Dev / BE Dev** — implements assigned tasks
- **QA** — validates PRs against accepted spec
- **Operator** — final merge authority, handles unresolvable escalations

**Stages:** Backlog → In Progress → In Review → QA → Completed → Blocked

**Shared medium:** Git repository (one cloned copy in `workspace/repo/`, one branch per dev per sprint, PR auto-updates as dev pushes)

**Definition of done:** PR opened, all tests pass, QA reviewed against spec, operator approves merge.

**Visual assets:** Mockups attached to tasks. FE Dev and QA need vision-capable models.

**RUNBOOK sections:**
- Local setup instructions
- Branch naming convention
- PR conventions
- Known codebase gotchas
- Deployment notes

**Workflow nuance:** Devs work one branch per sprint. Multiple tasks ship in one PR that auto-updates. QA re-reviews each push. Operator merges once everything passes.

---

## Marketing / Creative Team

**Roles:**
- **Strategist (client-facing)** — receives briefs, scopes campaigns, manages client relationship
- **Creative Director (feasibility reviewer)** — reviews briefs for fit with brand, channel, and budget
- **Copywriter / Designer / Producer** — produces deliverables
- **Brand Reviewer (QA)** — final quality check against brand guidelines
- **Operator** — handles escalations, approves controversial creative

**Stages:** Brief → Drafting → Internal Review → Client Review → Approved → Blocked

**Shared medium:** Google Drive folder, Notion workspace, or Figma project. Linked from `workspace/LINKS.md` if external.

**Definition of done:** Approved by Brand Reviewer, client has signed off, asset is delivered to client's specified location.

**Visual assets:** Often heavy use — mockups, references, photography. Stored as task attachments primarily.

**RUNBOOK sections:**
- Brand guidelines reference
- Channel-specific requirements (social character limits, email best practices, etc.)
- Asset rights and attribution rules
- Approval chain
- Standard turnaround times

**Workflow nuance:** Client approval is often a back-and-forth. Strategist owns those rounds and must clearly log each round in DECISIONS.md so the team doesn't lose context.

---

## Real Estate Team

**Roles:**
- **Listing Agent (client-facing)** — talks to sellers and buyers, owns the relationship
- **Broker (feasibility reviewer)** — reviews pricing, market fit, compliance
- **Listing Producer** — handles property write-ups, photo coordination, MLS entry
- **Compliance Reviewer (QA)** — checks all disclosures, contract terms before publishing
- **Operator** — handles unusual situations, contested pricing, escalations

**Stages:** New → Listing Prep → Listed → Under Offer → Closed → Blocked

**Shared medium:** CRM platform (BoomTown, Follow Up Boss, etc.). Reference URL in `workspace/EXTERNAL_SYSTEM.md`.

**Definition of done:** Listing live in MLS, photos approved, pricing confirmed, all disclosures complete.

**Visual assets:** Property photos. Stored as task attachments or CRM-hosted.

**RUNBOOK sections:**
- MLS data entry conventions
- Photography requirements (resolution, count, room order)
- Disclosure checklist
- Pricing methodology
- Compliance requirements specific to jurisdiction

**Workflow nuance:** Compliance is non-negotiable. QA reviewer must catch missing disclosures before listing goes live or there are legal consequences.

---

## Content / Editorial Team

**Roles:**
- **Editor in Chief (client-facing)** — owns editorial calendar, talks to publication owner
- **Senior Editor (feasibility reviewer)** — reviews pitches for fit with calendar and audience
- **Writer / Reporter** — produces drafts
- **Copy Editor (QA)** — final pass for grammar, accuracy, style
- **Fact Checker** — separate role if the team is research-heavy
- **Operator** — handles escalations, approves controversial pieces

**Stages:** Idea → Drafting → Editing → Fact Check → Published → Blocked

**Shared medium:** CMS or shared Drive folder. Reference linked.

**Definition of done:** Copy edited, fact-checked, scheduled or published.

**Visual assets:** Hero images, embedded images. Often pulled from stock libraries — sourcing rules matter.

**RUNBOOK sections:**
- House style guide
- SEO requirements (length, keyword conventions)
- Image sourcing and rights
- Citation and attribution conventions
- Publishing checklist

**Workflow nuance:** Fact-checking can introduce significant rework. Plan for it in time estimates.

---

## Sales / Outreach Team

**Roles:**
- **Account Executive (client-facing)** — manages prospects through close
- **Sales Leader (feasibility reviewer)** — reviews lead quality, qualifies opportunities
- **SDR / BDR** — handles initial outreach and qualification
- **Sales Ops (QA)** — reviews pipeline data quality, ensures CRM is clean
- **Operator** — handles escalations, signs off on non-standard deals

**Stages:** Lead → Qualifying → Engaged → Proposal → Closed-Won/Lost → Blocked

**Shared medium:** CRM (Salesforce, HubSpot). External reference in `workspace/EXTERNAL_SYSTEM.md`.

**Definition of done:** Deal closed (won or lost), CRM updated with full context, lessons logged in SHARED_MEMORY.md.

**Visual assets:** Rare. Possibly proposal decks attached to tasks.

**RUNBOOK sections:**
- Qualification criteria (MEDDIC, BANT, whatever the team uses)
- Outreach templates and sequences
- CRM hygiene rules
- Compliance (GDPR, CAN-SPAM, opt-out handling)
- Hand-off triggers between SDR and AE

**Workflow nuance:** Compliance is critical. Bad outreach has legal consequences. QA role focuses on this.

---

## Customer Success / Support Team

**Roles:**
- **CS Manager (client-facing)** — owns customer relationship, manages escalations
- **Tier 2 / Specialist (feasibility reviewer)** — reviews complex tickets, validates solutions
- **Tier 1 Support** — handles standard inquiries
- **QA Reviewer** — audits ticket resolutions for quality
- **Operator** — handles fire escalations, contract-level issues

**Stages:** New Ticket → In Progress → Awaiting Customer → Resolved → Blocked

**Shared medium:** Ticketing system (Zendesk, Intercom). External reference linked.

**Definition of done:** Ticket resolved, customer confirmed, post-resolution survey sent or scheduled.

**Visual assets:** Screenshots from customers. Stored as task attachments.

**RUNBOOK sections:**
- Knowledge base location
- SLA targets per tier
- Escalation triggers
- Tone and communication standards
- Common issue resolution playbooks

**Workflow nuance:** "Awaiting Customer" can sit for days. Have a clear policy for follow-up cadence and when to close as inactive.

---

## Operations Team

**Roles:**
- **Ops Lead (client-facing)** — receives requests from internal stakeholders
- **Senior Ops (feasibility reviewer)** — validates requests are doable / scoped correctly
- **Ops Specialist** — executes operational tasks
- **Audit Reviewer (QA)** — verifies completed work meets compliance requirements
- **Operator** — handles approvals, audit issues

**Stages:** Request → Triage → In Progress → Verification → Complete → Blocked

**Shared medium:** Varies widely. Could be spreadsheets, internal systems, dashboards.

**Definition of done:** Verified by audit reviewer, approval logged, change reflected in source-of-truth system.

**RUNBOOK sections:**
- Systems of record
- Approval thresholds (what requires operator sign-off)
- Audit trail requirements
- Compliance requirements

**Workflow nuance:** Audit trail is mandatory. Every change must be traceable to who requested it, who approved it, who executed it.

---

## Research Team

**Roles:**
- **Lead Researcher (client-facing)** — receives research questions, scopes them
- **Senior Researcher (feasibility reviewer)** — validates questions are answerable, scopes methodology
- **Researcher / Analyst** — does the actual research
- **Peer Reviewer (QA)** — validates findings before publication
- **Operator** — handles ambiguous findings, contested conclusions

**Stages:** Question → Investigating → Drafting → Peer Review → Published → Blocked

**Shared medium:** Notion / shared docs / a research database. Linked from `workspace/`.

**Definition of done:** Findings peer-reviewed, sources cited, report published.

**Visual assets:** Diagrams, charts. Sometimes papers/PDFs as input.

**RUNBOOK sections:**
- Source quality standards
- Citation format
- Peer review criteria
- Publication targets
- Confidence levels and how to express uncertainty

**Workflow nuance:** Research projects can run long. Use SHARED_MEMORY.md aggressively to avoid losing context across sessions.

---

## Custom / Hybrid Teams

If the user describes something that doesn't fit cleanly:

1. Map their description to the closest archetype
2. Adjust roles, stages, and shared medium accordingly
3. Pull RUNBOOK sections from the closest match
4. Mark anything inferred so the user can correct in Step 4 review

Common hybrid patterns:
- **Dev + Marketing for SaaS** — two related projects with shared agents
- **Sales + Customer Success** — different stages, often same team
- **Research + Editorial** — research informs content
- **Real Estate + Marketing** — listing + promotion

For these, suggest creating two separate projects rather than one mega-project. Agents can participate in both.


path: references/interview-questions.md
content: # Interview Question Banks

Extended question banks for the Pass 1 (Team Identity) and Pass 2 (Work Structure) interviews. Use the questions in SKILL.md as the core flow; consult this file when:
- The user answers ambiguously and you need follow-up questions
- The team type is unusual and you need specialized prompts
- You're filling gaps in the AI-drafted plan and need to know what's missing

---

## Table of Contents

- [Pass 1: Team Identity — Core](#pass-1-team-identity--core)
- [Pass 1: Team Identity — Follow-ups](#pass-1-team-identity--follow-ups)
- [Pass 2: Work Structure — Core](#pass-2-work-structure--core)
- [Pass 2: Work Structure — Follow-ups](#pass-2-work-structure--follow-ups)
- [Pass 2: Team-Type-Specific Probes](#pass-2-team-type-specific-probes)
- [Gap-Filling Heuristics](#gap-filling-heuristics)

---

## Pass 1: Team Identity — Core

These are the questions in SKILL.md, restated here for reference:

1. **Project purpose** — one-sentence description
2. **Team type** — software dev, marketing, real estate, content, sales, customer success, operations, research, or other (describe)
3. **Project name and ID** — display name + lowercase ID
4. **Agent roster** — which existing agents will be on this team and their per-project role
5. **Client-facing agent** — who receives intake and talks to the client
6. **Feasibility reviewer** — domain expert who validates work is doable before commitment
7. **Quality reviewer** — who checks completed work before client delivery
8. **Operator** — is there a human in the loop, and what's their alias
9. **Other roles** — specialized contributors

---

## Pass 1: Team Identity — Follow-ups

If a user's answer is vague or missing, dig deeper:

### If they don't know what to call their team type
> "Don't worry about the label — describe what the team produces or does. Examples: 'They write blog posts and social copy for our clients.' Or: 'They handle inbound leads and qualify them.' I can pick a category from there."

### If they say they don't have a clear feasibility reviewer
> "Even if you don't have a formal 'reviewer,' someone needs to look at incoming work and say whether the team can actually do it given current capacity, skills, or constraints. Who would catch a problem like 'this requires expertise nobody has' before the team commits to delivering it?"

### If they say they don't have QA
> "Someone needs to be the last set of eyes before the work goes to the client. It doesn't have to be a separate person — it could be the feasibility reviewer doing a final pass. But there should be someone designated. Who is it?"

### If they say no operator
> "If a problem can't be resolved by any agent — say a client goes silent for a week, or two agents disagree on something the spec doesn't cover — who steps in? Even if it's just you, that's the operator."

### If they want all agents to do everything
Push back gently:
> "Specialized roles produce better results than agents trying to do everything. I'll need at least: a client-facing role, a feasibility reviewer, and a QA reviewer. Pick which agents fill those — they can still do other work too."

---

## Pass 2: Work Structure — Core

Restated from SKILL.md:

1. Task manager (Asana / ClickUp)
2. Stages of work (column structure)
3. Shared working medium
4. Definition of "done"
5. Sprint mode (one-at-a-time vs continuous flow)
6. Escalation thresholds
7. Visual / media assets
8. Anything else specific

---

## Pass 2: Work Structure — Follow-ups

### If they're unsure what columns to use

Suggest a default based on team type, then customize. Sensible defaults below.

### If they say "we don't have a shared working medium"
> "Even if work is mostly conversational, agents need somewhere to read shared context — past decisions, current state, reference material. That can be the project folder itself (`workspace/`). Is that enough, or do you have an external system the team uses?"

### If they're confused about sprint mode
> "Think about how new work arrives. Does the client typically hand you one big chunk to do well, or a steady stream of small things? Big chunks → sprint mode. Steady stream → continuous flow. You can change this later."

### If escalation thresholds feel arbitrary
> "These exist so agents don't spin wheels burning AI tokens. The defaults — 24 hours stuck, 2 re-escalations, 48 hours waiting on client — are reasonable for most teams. If your work is faster-paced (e.g., same-day turnaround), tighten these. If slower (e.g., long research projects), loosen them."

### If they're unclear on visual/media handling
Ask:
- "Will any agent need to look at images, video, or audio to do their work?"
- "Will any agent need to produce images, video, or audio as output?"

If either is yes → visual handling needed.

---

## Pass 2: Team-Type-Specific Probes

Use these to flesh out the plan when the user picks a particular team type.

### Software Development
- Frontend / backend / full-stack split?
- Branch and PR conventions? (default suggested in workflow.md)
- Local dev environment standardized?
- Deployment owned by team or separate?
- Test conventions — required or aspirational?

### Marketing / Creative
- Brand guidelines location?
- Channel mix (social, blog, email, paid)?
- Creative director or copy lead?
- Asset library / DAM in use?
- Approval chain — does client see drafts or only finals?

### Real Estate
- Listing source — MLS or direct?
- Photography handled by team or external?
- Pricing authority — who signs off?
- CRM platform?
- Compliance / disclosure requirements?

### Content / Editorial
- Editorial calendar in place?
- Editor / copy editor / fact-checker chain?
- CMS in use?
- SEO requirements?
- Image sourcing rules (rights, attribution)?

### Sales / Outreach
- CRM platform?
- Lead source(s)?
- Qualification criteria?
- Hand-off to closer / account manager?
- Compliance (GDPR, CAN-SPAM, etc.)?

### Customer Success / Support
- Ticketing platform?
- Tier 1 / Tier 2 split?
- Knowledge base location?
- SLA targets?
- Escalation path for technical issues?

### Operations
- What's the operational scope? (logistics, finance, HR ops, etc.)
- Systems of record?
- Approval workflows?
- Audit / compliance requirements?

### Research
- Research domain?
- Sources (papers, web, internal data)?
- Output format (reports, briefings, structured data)?
- Peer review chain?

### Other / Custom
Ask:
- "Walk me through what the team does end-to-end. Start when work arrives, end when it's delivered."
- "Where does the team produce its work?"
- "Who reviews before delivery?"
- "What can go wrong, and who handles it?"

---

## Default Stage Suggestions by Team Type

Use these as starting points. Confirm with user before locking in.

| Team Type | Suggested Stages |
|---|---|
| Software Dev | Backlog → In Progress → In Review → QA → Completed → Blocked |
| Marketing | Brief → In Drafting → Internal Review → Client Review → Approved → Blocked |
| Real Estate | New → Listing Prep → Listed → Under Offer → Closed → Blocked |
| Content | Idea → Drafting → Editing → Fact Check → Published → Blocked |
| Sales | Lead → Qualifying → Engaged → Proposal → Closed-Won/Lost → Blocked |
| Customer Success | New Ticket → In Progress → Awaiting Customer → Resolved → Blocked |
| Operations | Request → Triage → In Progress → Verification → Complete → Blocked |
| Research | Question → Investigating → Drafting → Peer Review → Published → Blocked |

Every team should have a "Blocked" column for work that's stuck waiting on something external.

---

## Gap-Filling Heuristics

When writing the AI-drafted plan in Step 4, you'll inevitably need to fill gaps the user didn't explicitly answer. Use these heuristics. Mark all inferred items with [INFERRED] in the plan.

### Communication frequency
If unspecified, default: agents check their queue at every session start, before any other action.

### Sprint length
If unspecified and using sprint mode, do not invent a fixed length. Sprints end when all committed work is delivered, not on a calendar.

### Re-work loops
If unspecified, default: failed QA review → back to executor with specific failures listed → re-submit when fixed. Same dev escalation rules apply during rework.

### Idle behavior
If unspecified, default: when nothing is in their queue and no task is assigned to them, agents do nothing (do not invent work).

### Decision authority
If unspecified, default: feasibility-reviewer has technical authority within the project; client-facing agent has client-relationship authority; operator has final authority on anything contested.

### "Done" definition
If unspecified for the team type, default: "QA reviewed and approved against the accepted scope, and the operator (if any) has signed off on delivery." Adjust per team.

### Versioning of accepted scope
Always default: scope documents are versioned (`SPEC-v1-[date].md`) and never overwritten. Latest accepted version is referenced from `SPEC-CURRENT.md`. This is universal across team types.

### Mid-sprint scope changes
If unspecified, default: scope changes mid-sprint require client-facing agent to pause work, log the change in DECISIONS.md, get explicit re-acceptance from client, and update SPEC. Avoid silent scope drift.


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