Background

The biggest pain point for small teams isn’t technical — it’s attention fragmentation. You’re tracking project progress, following up on issues, reviewing PRs, and responding to ad-hoc requests all at once. When there’s too much to do with too few people, you end up in a state where everything is in motion but nothing is getting done.

Our solution: Linear + GitHub as the management foundation, with OpenClaw serving as agile coach and project manager. The agile development rhythm provides the skeleton. Humans only appear at key decision points — monitoring, reminders, and coordination are all handled by OpenClaw.

---

Tool Stack

Why Linear over Jira or Notion? Speed, API experience, and simple GitHub integration. It doesn’t get in the way.

---

Agile Flow Overview

Rather than starting from “tool operations,” we start from development rhythm. The entire flow is a loop:

graph LR
    A[Intake] --> B[Backlog Grooming]
    B --> C[Sprint Planning]
    C --> D[Development]
    D --> E[Code Review]
    E --> F[Done]
    F --> G[Retrospective]
    G -- feedback loop --> A

OpenClaw has a defined role at each phase. Humans appear only at key decision points.

---

Fit with Agile

Before diving into each phase, it’s worth being honest: this workflow isn’t a textbook agile implementation. It’s a variant that makes deliberate trade-offs within the agile framework — some parts align closely, others deviate meaningfully.

Where It Fits

Iteration rhythm: Sprint planning, backlog grooming, and status transitions are all preserved. OpenClaw’s role is to reduce execution friction, not bypass these practices.

Fast feedback loops: CI failure notifications, PR timeout reminders, overdue issue check-ins — these all embody agile’s core principle of surfacing problems quickly. OpenClaw compresses feedback latency from “discovered at next standup” to “real-time awareness.”

Reduced ceremony overhead: Agile often fails in small teams because the process itself is too heavy — developers don’t want to maintain it. OpenClaw takes over the mechanical work of creating issues, applying labels, and updating statuses, letting the team actually practice agile rather than just claiming to.

Continuous delivery: PR merged = done. OpenClaw orchestrates Claude Code for initial review, supporting a high-frequency, small-batch delivery rhythm.

AI Tools as Team Roles

The key to understanding this workflow’s agile fit is reframing what “tool” means. Claude Code, Codex, GitHub Copilot Agent, and Cursor aren’t just software with different features — they each have distinct role boundaries within the process:

OpenClaw’s role as agile coach and project manager is fixed. The other tools are dynamically assigned by OpenClaw based on task characteristics — the same issue might use Claude Code during planning and Copilot Agent or Codex during implementation. There’s no hard-coded mapping (see “How OpenClaw Selects Tools” below).

From this perspective, this workflow isn’t “one person running a process with tools.” It’s a virtual team of humans and AI roles running agile together. The cross-functional collaboration agile calls for still exists — the team just went from “multiple human engineers” to “one human developer + multiple AI execution roles orchestrated by OpenClaw.”

Real Limitations

Clear role division doesn’t mean no limitations. Two real ones:

Sprint retrospectives lack a fixed cadence. Currently triggered manually, with no enforced sprint cycle length. This is a process gap, independent of team size.

Execution quality depends on context quality. Claude Code’s planning ability depends on how clearly the issue is described. Codex’s execution quality depends on how well-scoped the task is. When context is thin, the quality of OpenClaw-orchestrated execution drops noticeably and requires more human correction.

In short: this workflow isn’t a simplification of agile — it’s an expansion of who counts as a “team member.” OpenClaw and the AI tools it orchestrates are genuine collaborators, not just automation scripts assisting humans. That said, the current coverage is limited to technical execution. Cross-team alignment, business decisions, and user acceptance still require humans.

---

Phase 1 · Requirement Intake

The biggest problem with requirement management isn’t “no tool” — it’s that the act of recording has friction. You notice a bug mid-development, but opening Linear, filling in the title, selecting priority, choosing type — by the time you’re done, you’ve lost your train of thought. So you either don’t record it, or it ends up in a notes app you’ll never find again.

The solution here: make OpenClaw the first receiver of requirements. Recording drops to “say one sentence.”

Most common method: tell OpenClaw directly

You’re mid-development and notice an edge case. No need to context-switch — just say:

“The login page shows no error when the network times out — users have no idea what happened”

OpenClaw converts this to a structured issue, infers acceptance criteria, and sends a confirmation:

[Bug] Login page: no error on network timeout · Medium · Created PROJ-47 Acceptance criteria: - [ ] Show a clear error message on timeout - [ ] Message is actionable — user knows what to do Confirm?

Acceptance criteria are written into the issue description alongside the issue itself — AI execution later reads directly from Linear, no need to hunt for context. Confirm or ignore — the issue lands in Backlog either way. No context switch required.

Create directly in Linear

Sometimes requirements come from product discussions or external feedback. Creating the issue directly in Linear is more natural. OpenClaw detects new issues on the next scan and automatically routes them into the grooming flow.

Code first, record later

Common in small teams: you ship a small feature, then remember you never created an issue. Just tell OpenClaw:

“Just finished the user avatar upload — can you log it?”

OpenClaw creates the issue and marks it Done immediately — you have a record without pretending it’s still in progress.

---

Phase 2 · Backlog Grooming (OpenClaw proactively, no trigger needed)

An issue entering the Backlog doesn’t mean it’s been handled. An issue with no label, no priority, and no complexity estimate is just a pile of text — you’ll have to think through it from scratch at the next sprint planning anyway.

OpenClaw intervenes immediately when an issue enters the Backlog. The goal: every issue is “ready to start” before it gets scheduled.

Label + Priority

OpenClaw reads the issue description and automatically determines type (Bug / Feature / Chore / Docs / Auto) and priority (Urgent / High / Medium / Low), writing directly to Linear.

The Auto label is OpenClaw’s exclusive marker: it signals that this task can be completed independently by AI tools. OpenClaw will proactively schedule and execute it, and include it in concurrency control during Heartbeat monitoring.

This initial judgment doesn’t need to be perfect — just good enough. Developers can change anything they disagree with, no explanation needed. OpenClaw won’t ask why or reset it next time. Priority is based on impact and urgency: production outages are Urgent, new features typically start at Medium.

Complexity Pre-Assessment

Most issues just need a label. But some look simple on the surface and hide many decision points — “add multi-language support” sounds straightforward, but it involves i18n framework selection, string extraction strategy, and build pipeline changes. Any one of those can block you.

If any of these conditions are met, OpenClaw calls Claude Code for a rough technical pre-assessment (analysis only, no code written):

• Description is more than 5 lines, or contains multiple parallel sub-requirements
• Involves architecture changes, refactoring, API design, or database schema changes

The assessment is appended directly to the issue description. Developers see it when they open the issue — no hunting for context.

If estimated effort exceeds 3 days, OpenClaw suggests splitting: the original issue becomes an Epic, with child issues created for independently deliverable pieces. A confirmation is sent to the developer. No response = approved.

The goal of splitting isn’t to create more issues — it’s to ensure every issue can be completed in 1–3 days. Clearer status transitions, and easier to spot where things are stuck.

Planning Output Storage

• Current implementation plan → appended to issue description, bound to the issue, won’t get lost
• Long-term reference content (API docs, architecture notes) → written to Obsidian project directory for later lookup

---

Phase 3 · Sprint Planning (OpenClaw proactively)

Traditional sprint planning pain: meetings, manual dragging of issues, estimation. This process makes sense for teams of 5+, but in a 1–3 person team it usually becomes “30-minute meeting every Monday, then everyone does what they were going to do anyway.”

This workflow hands scheduling judgment to OpenClaw, but distinguishes two cases: auto-schedule what can be automated, and only push recommendations for decisions that need humans.

Two Task Types, Two Scheduling Logics

🤖 Automatic tasks (AI tools can complete independently, no developer in Cursor required)

These tasks have clear boundaries, defined execution paths, and don’t need the developer watching. OpenClaw proactively schedules them into Todo based on priority:

• Urgent / High → immediately move to Todo, send a notification
• Medium → auto-move when current In Progress count < 2, otherwise stay in Backlog
• Low → don’t auto-schedule, wait for explicit instruction

🧑‍💻 Manual tasks (require developer to code in Cursor)

OpenClaw doesn’t auto-schedule these — the developer’s time and focus are finite, and when to start a deep-work task should be a human decision. OpenClaw only sends recommendations:

📋 3 manual tasks pending scheduling, highest priority:
[Feature] User permission management (High)
[Bug] List page scroll lag (High)
Add to this sprint?

After the developer confirms, OpenClaw executes the status change. If you don’t want to schedule now, just ignore it — it’ll come up again next scan.

Concurrency Control

Too many simultaneous tasks is a common small-team trap — everything is moving, but nothing is progressing. OpenClaw enforces limits on two dimensions:

• Automatic tasks: no more than 3 concurrent, to avoid AI tools competing for context and resources
• When automatic + manual combined exceeds 5: OpenClaw proactively flags: ⚠️ 5 tasks currently in progress — consider finishing some before starting new ones

This isn’t a hard block. Developers can ignore it. But at least they’ll be aware of the current concurrency state.

---

Phase 4 · Development

Once an issue enters Todo, development begins. OpenClaw’s role in this phase varies significantly by task type — sometimes it’s the full orchestrator, sometimes just a quiet monitor.

Starting a Task

Say “start GEO-47” and OpenClaw updates the status to In Progress, then determines how to approach it:

• If the developer says “I’ll handle it myself,” OpenClaw steps back to monitoring mode
• If it was marked as an automatic task during sprint planning, OpenClaw enters drive mode
• If unclear, OpenClaw asks once: “Should I handle this or will you?” — asked once, not repeatedly

OpenClaw Full-Drive (Automatic Tasks)

For tasks with clear boundaries that don’t require the developer in Cursor, OpenClaw handles everything.

Typical scenarios: generating unit tests for an API set, adding JSDoc to a module, generating a PR description from existing code.

The flow: OpenClaw first reads the acceptance criteria from the issue’s ## Acceptance Criteria section in Linear, confirms the target, then selects the tool (Claude Code or Codex), generates a plan, and sends it to the developer for confirmation. Execution only happens after approval. OpenClaw never auto-pushes code — code entering the repository always requires human confirmation.

Developer Manual (Cursor)

For deep coding tasks, the developer works in Cursor and OpenClaw steps back. Create a branch, start writing:

git checkout -b feature/GEO-47-user-permission

OpenClaw doesn’t touch the local IDE during this phase, but is always available. Hit a blocker? Just say:

“Not sure which layer the permission validation logic in GEO-47 should live in”

OpenClaw calls Claude Code to analyze the current architecture and sends a specific recommendation — not “consider middleware” but “based on your existing auth/ directory structure, the guards/ layer makes sense because…”

Mixed Mode (Most Common in Practice)

Most tasks are actually mixed:

• Planning phase (figuring out how) → OpenClaw orchestrates Claude Code for analysis
• Implementation phase (writing code) → developer handles manually in Cursor
• Wrap-up phase (tests, PR description) → OpenClaw orchestrates Codex to generate

The developer only goes deep on “writing code.” Everything before and after is handled by OpenClaw.

How OpenClaw Selects Tools

OpenClaw decides which tool to call based on task characteristics — no developer input needed:

When uncertain, default to Claude Code. When the task is crystal clear, Codex is faster. When full GitHub-native autonomous execution is needed, use Copilot Agent.

In-Development Monitoring

If an issue has been In Progress for more than 3 days with no associated PR, OpenClaw proactively asks:

“GEO-47 has been in progress for 3 days — want to split it or have me help analyze the blocker?”

Not nagging — just a reminder. Issues often get stuck because scope was larger than expected. Splitting is usually more effective than pushing through.

---

Phase 4.5 · Acceptance Gate (AI Tasks Only)

This is the most critical mechanism in this workflow.

Context: For manually developed tasks, the developer knows when it’s done. But AI-driven automatic tasks are different — after Claude Code or Codex finishes execution, someone needs to verify whether the code actually meets requirements, whether edge cases were missed, and whether the syntax is clean. OpenClaw plays this gatekeeper role.

Why Not Go Through Code Review (Phase 5)?

The traditional PR flow assumes a developer manually pushes a branch and opens a PR. After an automatic task executes, there may not be a PR — the code might be committed directly to a branch. Phase 4.5 is more direct and doesn’t require that detour.

Acceptance Flow

1. Read acceptance criteria

Read directly from the issue’s ## Acceptance Criteria section in Linear — this is why acceptance criteria must be written clearly when creating the issue: the AI execution starting point and the acceptance endpoint need to align.

2. Code quality check

Basic syntax and import checks, using commands appropriate for the project language.

3. Functional verification

Check each acceptance criterion item by item, recording results for each.

4. Write acceptance report to Linear

Results are written as a comment directly on the issue, permanently accessible. Format:

## Acceptance Report
Time: 2026-03-19 21:30

Acceptance Criteria Check
- [x] Clear error message shown on timeout: ✅ Implemented — displays "Network timeout, please retry"
- [x] Message is actionable, user knows what to do: ✅ Includes retry button

Conclusion: ✅ Passed

5. Acceptance failure → auto-fix loop

Key design: when acceptance fails, OpenClaw doesn’t immediately escalate — it first attempts to fix the issue itself:

Acceptance failed
    ↓
OpenClaw determines failure type, selects tool (Claude Code / Codex)
    ↓
Dispatches tool to fix, re-runs acceptance
    ↓
Max 2 automatic fix attempts
    ↓
3rd failure → stop, escalate for human intervention:
🔴 PROJ-47 acceptance failed 3 times consecutively — human intervention required
Failed items: [specific list]

Retry counts are persisted in heartbeat-state.json — session restarts don’t reset them. Once the limit is exceeded, no further attempts are made until the developer decides.

---

Phase 5 · Code Review

PR opened. OpenClaw detects a new PR on the branch, immediately updates the issue status to In Review, and kicks off a Claude Code analysis in an isolated directory.

⚠️ AI automatic tasks skip this phase — they go directly through Phase 4.5 Acceptance Gate.

What AI Review Does and Doesn’t Do

This step is triage, not a replacement for human review. Claude Code focuses on:

• Logic bugs: boundary conditions, null handling, async race conditions
• Security issues: unvalidated input, sensitive data exposure, permission bypasses
• Obvious performance problems: unnecessary full-table queries, repeated computation in loops

Review findings are sent to the developer — not posted directly to GitHub. Reason: AI comment quality is inconsistent. Posting directly can cause confusion or make the PR look noisy. The developer decides what’s worth sharing and what to ignore.

In practice: AI review usually catches 1–2 boundary issues you missed. Occasional false positives, but the filtering cost is far lower than reviewing from scratch.

PR Description Generation

Many developers write PR descriptions by copying the issue title and adding “fixed xxx.” That’s not useful for reviewers.

When you need a good PR description, tell OpenClaw. It calls Codex to read the diff and generates a draft covering what changed, what’s affected, and testing notes. Copy and edit a few lines — much faster than starting from blank.

Timeout Reminders

• PR open for more than 24 hours without merge → OpenClaw sends a reminder, preventing PRs from silently aging in the queue
• CI failure → OpenClaw notifies immediately, no need to refresh GitHub Actions

---

Phase 6 · Done

There are two paths to Done:

• Traditional PR path: PR merged — OpenClaw detects this and automatically updates the issue status to Done, sending a completion notification
• AI automatic task path: Phase 4.5 Acceptance Gate passed — Linear status is updated directly to Done, with an acceptance completion notification

Most manually developed issues take the first path. AI-driven automatic tasks take the second.

How Careful to Be When Closing an Issue

Done is automatic. Canceled is not — this status can only be initiated by the developer.

Canceling requirements is common: product direction shifts, higher-priority work supersedes it, implementation cost turns out to be far higher than expected. But casually closing an issue carries risk: there might be an associated PR still open, code changes that need reverting, or other issues depending on it.

So before executing Canceled, OpenClaw sends a checklist:

About to close GEO-47. Please confirm:

• Any associated PRs still open?
• Any merged code that needs reverting?
• Any other issues depending on this one?

Confirm to close.

The developer checks each item, then OpenClaw executes the status change. This isn’t bureaucracy — it’s preventing “closed issue, open loose ends.”

Knowledge Capture After Completion

After each issue is done, OpenClaw asks:

“Anything from this one worth archiving to the docs?”

Lightweight, not mandatory. But in practice, many valuable decisions — why this approach was chosen, what pitfalls were hit, what follow-ups are needed — get captured at this moment. Left unrecorded, they’re forgotten in two weeks.

---

Phase 7 · Retrospective

At the end of a sprint, or whenever you want a status check, say “sprint report” or “project status.” OpenClaw pulls Linear data and generates a summary:

📊 This Week's Progress (GEO Project)

✅ Completed: 5
   · GEO-43 Login page timeout error message
   · GEO-44 User avatar upload
   · GEO-45 Permission validation refactor
   · GEO-46 API documentation
   · GEO-47 List page performance optimization

🔄 In Progress: 2
   · GEO-48 Multi-language support (In Progress · 4 days)
   · GEO-49 Email notification templates (In Review · awaiting merge)

📋 Pending: 8 (Backlog)
   · Highest priority: GEO-51 Payment flow refactor (High)

⚠️ Needs attention:
   · GEO-48 has been in progress 3+ days with no PR — consider splitting?

This report isn’t for reporting up — it’s so the developer can see in one place: what’s actually being worked on, where things are stuck, and what comes next.

Currently triggered manually. Can be configured to auto-send on a fixed schedule as a sprint-end rhythm anchor.

---

Status Transition Reference

graph LR
    Backlog --> Todo
    Todo --> InProgress[In Progress]
    InProgress -- "manual task, PR open" --> InReview[In Review]
    InReview -- PR merged --> Done
    InProgress -- AI automatic task --> Gate["Phase 4.5 Acceptance Gate"]
    Gate -- Pass --> Done
    Gate -- Cancel --> Canceled

Key design: All status transitions are triggered by OpenClaw via the Linear API — no dependency on platform-level integrations. Integration failures are silent errors; OpenClaw scans proactively and alerts immediately on failure. Status remains controllable.

---

Conventions

Branch Naming

feature/GEO-{id}-short-description
fix/GEO-{id}-short-description

The GEO-{id} in the branch name is the only signal OpenClaw uses to link a PR to an issue. Wrong format = broken linkage.

PR Description Template

## Changes
- Added xxx feature

## Testing
- Tested locally

Fixes GEO-123

---

Tool Orchestration Summary

Core principle: Cursor is always operated by the developer. OpenClaw never touches the local IDE. For everything else, OpenClaw independently selects the most appropriate tool — no developer input required.

---

What It Actually Feels Like

Running this in practice, the most noticeable changes:

• Fewer “forgot to follow up” moments: OpenClaw proactively reminds when issues time out or PRs sit too long — no relying on memory
• Less context switching: No need to open Linear to create an issue — just tell OpenClaw
• Code review gets pre-filtered: Low-level mistakes caught before PR merge
• Backlog stops being a junk drawer: Every incoming issue gets a priority and label automatically

Still unsolved:

• OpenClaw-generated PR descriptions are sometimes too generic and need human polish
• For complex business logic, Claude Code’s planning quality depends heavily on how detailed the context you provide is

---

Summary

The core idea of this workflow isn’t “use AI tools to replace developers.” It’s letting OpenClaw handle the parts that consume attention but don’t require human judgment — status tracking, monitoring, initial review, documentation — while keeping important decision points with humans.

For small teams and solo founders, the boundary is fairly clear: anything with clear rules that can be executed mechanically goes to OpenClaw; anything requiring contextual judgment or significant impact stays with humans.

Appendix: Workflow Configuration

The following is the complete content of the 05-project-management.md workflow currently running in production (sensitive information redacted), along with the project monitoring section of OpenClaw Heartbeat — for reference and replication.

---

05-project-management.md (Full SOP)

---
title: "Project Management & Automated Development"
created: 2026-03-17
ttl: 90d
status: active
skills: [linear-cli, github, coding-agent]
tags: [project-management, linear, github, automation, ai-coding, agile]
---

# Project Management & Automated Development

> Agile development rhythm as the foundation, Linear + GitHub as the base layer,
> OpenClaw as the automation middleware — optimized for minimum attention overhead.

⚠️ **Read `PROJECTS.md` before executing**: Get project IDs, GitHub repo mappings, preferred tools/models, monitoring scope.

---

## Triggers

**Trigger phrases:**
project status, check XX, XX is done, there's a bug, create issue, sprint report, help me create issue,
start developing XX, pre-schedule, split task

---

## Configuration (Single source of truth)

> ⚠️ API keys, Team ID, Project IDs, State IDs are maintained here only.

LINEAR_API_KEY   = "lin_api_****"
LINEAR_GRAPHQL   = "https://api.linear.app/graphql"
LINEAR_TEAM_ID   = "YOUR_TEAM"
LINEAR_TEAM_UUID = "****-****-****-****-****"

### Project IDs

| Project | Project ID | Local Path |
|---------|-----------|-----------|
| ProjectA | `****` | `/path/to/ProjectA` |
| ProjectB | `****` | `/path/to/ProjectB` |
| ...      | `****` | `...`               |

### State IDs

| State | ID |
|-------|----|
| Backlog | `****` |
| Todo | `****` |
| In Progress | `****` |
| In Review | `****` |
| Done | `****` |
| Canceled | `****` |

### Label Conventions

| Label | Meaning |
|-------|---------|
| `Bug` | Bug fix |
| `Feature` | New feature |
| `Chore` | Miscellaneous tasks |
| `Docs` | Documentation updates |
| `Auto` | AI-executable task (Heartbeat monitoring signal — required when scheduling as automatic task) |

### Issue Naming Conventions

- Feature: `[Feature] short description`
- Bug: `[Bug] short description`

### Branch Naming Conventions

feature/{ISSUE_ID}-short-description
fix/{ISSUE_ID}-short-description

> `{ISSUE_ID}` is the identifier returned by Linear (e.g. `PROJ-123`). No fixed prefix dependency.
> Branch name containing `{ISSUE_ID}` is the only signal OpenClaw uses to link a PR to an issue.

### AI Tool Assignment

| Phase | Tool | Triggered By | Purpose |
|-------|------|-------------|---------|
| Planning | Claude Code | OpenClaw background call | Technical planning, architecture, complexity analysis |
| Implementation (developer manual) | Cursor | Developer explicitly says "I'll handle it" | Local IDE coding — OpenClaw doesn't intervene |
| Implementation (AI-driven) | Claude Code / Codex / Copilot Agent | **OpenClaw decides** | See "Tool Decision Rules" |
| Review | Claude Code | OpenClaw automatic (PR open) | Diff analysis, issue flagging |

### OpenClaw Tool Decision Rules

| Scenario | Claude Code | Codex | Copilot Agent |
|----------|:-----------:|:-----:|:-------------:|
| Ambiguous task description, needs context understanding | ✅ | | |
| Cross-file analysis / architecture judgment | ✅ | | |
| Bug cause unclear, needs reasoning | ✅ | | |
| Documentation wrap-up | ✅ | | |
| Clear task, small scope, defined steps | | ✅ | |
| Generating test cases | | ✅ | |
| Generating PR descriptions | | ✅ | |
| Bug fix (root cause already identified) | | ✅ | |
| GitHub issue assigned directly to AI for full autonomous execution | | | ✅ |

Default: Claude Code. When task is crystal clear: Codex. When GitHub-native full flow needed: Copilot Agent.

---

## Agile Flow Overview

```mermaid
graph LR
    A[Intake] --> B[Backlog Grooming]
    B --> C[Sprint Planning]
    C --> D[Development]
    D --> E[Code Review]
    E --> F[Done]
    F --> G[Retrospective]
    G -- feedback loop --> A

---

Phase 1 · Requirement Intake

Entry: Triggered at any time (Telegram / create directly in Linear)

Three Sources

A. Tell OpenClaw (most common) State the requirement → OpenClaw creates issue via Linear CLI/API → sends confirmation ⚠️ Issue description must include ## Acceptance Criteria section (format: - [ ] criterion) If not explicitly provided, OpenClaw infers and writes it, then sends confirmation with criteria included

B. Create directly in Linear OpenClaw detects new Backlog issue on next scan → enters Phase 2 ⚠️ If ## Acceptance Criteria section is missing, OpenClaw proactively fills it in and sends confirmation

C. Code first, record later Say “xxx is done, please log it” → OpenClaw creates issue and immediately marks Done

Exit: Issue exists in Backlog with ## Acceptance Criteria section in description

---

Phase 2 · Backlog Grooming (OpenClaw proactive, no trigger needed)

Entry: Issue enters Backlog

2.1 Apply Label

Determine type from issue title and description, set via Linear API. Default to Feature when uncertain.

2.2 Assess Priority

OpenClaw sets directly. Change it if you disagree — no explanation needed.

2.3 Complexity Pre-Assessment

Trigger Claude Code pre-assessment (analysis only, no code) if any of these apply:

• Issue description > 5 lines / contains multiple sub-requirements
• Keywords include “architecture”, “refactor”, “API design”, “database schema”

If estimated effort > 3 days → auto-split:

• Original issue becomes Epic
• Child issues created in [Subtask] description format, linked to parent
• Split result sent for confirmation (no response = approved)

Planning output storage:

• Current plan → appended to Linear issue description
• Long-term reference docs → Obsidian project directory

Exit: Label applied, priority set, complex issues split

---

Phase 3 · Sprint Planning (OpenClaw proactive)

3.1 Two Task Types, Two Scheduling Logics

🤖 Automatic tasks (Auto label — OpenClaw can independently orchestrate tools to complete)

• Urgent / High → immediately move to Todo, send notification
• Medium → auto-move when In Progress count < 2
• Low → don’t auto-schedule, wait for instruction

🧑‍💻 Manual tasks (developer explicitly says “I’ll handle it”, or requires local IDE)

• OpenClaw doesn’t auto-move to Todo, only sends recommendations: 📋 N manual tasks pending scheduling, highest priority: {ISSUE_ID} [title] — add to this sprint?
• Execute status change only after confirmation

3.2 Concurrency Control

• In Progress automatic tasks: no more than 3
• When automatic + manual combined exceeds 5: send alert

Exit: Issue status is Todo, development mode confirmed (automatic/manual)

---

Phase 4 · Development

4.1 Pick Up Issue

Say “start {ISSUE_ID}” →

1. Linear API: Todo → In Progress
2. Send: 🚀 {ISSUE_ID} development started

4.2 Development Mode Selection

''' Explicitly says “I’ll handle it” ├── YES → Mode B (manual) └── NO → Check Phase 3 scheduling mark ├── Automatic task → Mode A (AI full-drive) └── Unclear → Ask once: “Should I handle this or will you?” '''

Mode A: AI full-drive

1. Select Claude Code or Codex per “Tool Decision Rules”
2. Generate plan and send for confirmation (must confirm before implementation — no auto-coding)
3. Confirmed → execute; no response after 30min → send reminder

Mode B: Manual development (OpenClaw steps back to monitoring role)

1. Create branch locally: git checkout -b feature/{ISSUE_ID}-description
2. Develop in Cursor — OpenClaw doesn’t intervene
3. Hit a blocker → tell OpenClaw → analyzes per tool decision rules

4.3 AI Task Development Standards

Before development (required):

1. linear issue view {ISSUE_ID} — confirm ## Acceptance Criteria exists
2. If missing → infer and fill in, send confirmation
3. Send: 🤖 {ISSUE_ID} AI implementation starting

After development, hand off to acceptance (required):

• Code has been git add && git commit
• Send: ✅ {ISSUE_ID} code complete, awaiting acceptance

4.4 In-Development Monitoring

In Progress for more than 3 days with no associated PR → send: ⏰ {ISSUE_ID} has been in progress 3 days — still working on it? Need to split or get help?

Exit: Code committed → enter Phase 4.5 Acceptance Gate

---

Phase 4.5 · Acceptance Gate (Gatekeeper Mechanism)

⚠️ All AI-implemented automatic tasks must pass this Gate before Linear Done status is updated. Manually completed tasks may skip.

Entry: AI implementation completion notification, or Heartbeat fallback trigger

Acceptance Flow

Step 1: Read acceptance criteria from Linear '''bash linear issue view {ISSUE_ID} ''' Extract ## Acceptance Criteria section, list each check item.

Step 2: Code quality check (determine by project type) '''bash

Python

python3 -m py_compile python3 -m pytest tests/ -v

Swift/iOS

xcodebuild build -scheme -destination ‘platform=iOS Simulator,name=iPhone 16’ '''

Step 3: Functional verification Check each ## Acceptance Criteria item, record result for each.

Step 4: Submit acceptance report to Linear '''bash linear issue comment {ISSUE_ID} —body ”## Acceptance Report Time: YYYY-MM-DD HH:MM

Acceptance Criteria Check

• Criterion A: result description
• Criterion B: failed (reason)

Conclusion: ✅ Passed / ⚠️ Needs fixes” '''

Step 5: Branch handling

✅ Acceptance passed:

• linear issue move {ISSUE_ID} --to "Done"
• Send: ✅ {ISSUE_ID} acceptance passed

⚠️ Acceptance failed → auto-fix loop (max 2 attempts):

1. Determine failure type, select fix tool
2. Dispatch Claude Code / Codex to fix, re-run Steps 2–4
3. 3rd failure → stop auto-fix, escalate for human intervention: 🔴 {ISSUE_ID} acceptance failed 3 times consecutively — human intervention required / Failed items: [detailed list]

Acceptance Pass Criteria

1. All ## Acceptance Criteria items checked
2. Code quality check passed
3. Core functionality verified (minor issues allowed if noted in report)
4. Acceptance report written to Linear issue comment

Exit: Linear status Done (passed), or human intervention (consecutive failures)

---

Phase 5 · Code Review

Entry (traditional PR flow only): Heartbeat detects new PR (branch name contains {ISSUE_ID})

⚠️ AI automatic tasks skip this phase — they go directly through Phase 4.5 Acceptance Gate.

5.1 Status Sync

Linear API: In Progress → In Review

5.2 AI Review Auto-Trigger

'''bash REVIEW_DIR=$(mktemp -d) git clone https://github.com/your-org/{repo}.git $REVIEW_DIR cd $REVIEW_DIR && gh pr checkout {pr_number} claude —permission-mode bypassPermissions —print
‘Review this PR. Focus on: logic bugs, security issues, performance problems. Be concise.’ '''

Review findings sent to developer — not posted directly to GitHub. Developer decides whether to share.

5.3 PR Status Monitoring

• PR open > 24h without merge → send reminder
• CI failure → immediately send: 🔴 {ISSUE_ID} PR #N CI failed

Exit: PR merged

---

Phase 6 · Done

Entry A (traditional PR flow): Heartbeat detects PR merged Entry B (AI automatic tasks): Phase 4.5 Acceptance Gate passed

6.1 Status Sync

PR merged scenario: Linear API: In Review → Done Send: ✅ {ISSUE_ID} [title] completed — PR #N merged

AI automatic task scenario: Linear status already updated in Phase 4.5. Only send: ✅ {ISSUE_ID} acceptance complete

6.2 TODO.md Sync Rules

After AI automatic task completion, sync update to local TODO.md (project root).

6.3 Canceled Validation Check

Initiate close → send checklist, wait for confirmation before executing:

''' ⚠️ {ISSUE_ID} preparing to Canceled — confirm the following:

• Any associated open PRs? (close or transfer first)
• Any committed but un-reverted code?
• Any other tasks depending on this issue?
• Should cancellation reason be added to issue description? Reply “confirm close” when ready '''

6.4 Archive Reminder

If this development produced archivable documentation → send: 📝 {ISSUE_ID} complete — write to docs?

---

Phase 7 · Retrospective

Trigger: Say “sprint report” / “project status” / “retrospective”

Send format: ''' 📊 This Week’s Progress ([Project Name])

✅ Completed: N · {ISSUE_ID} title

🔄 In Progress: N · {ISSUE_ID} title (In Progress · X days)

📋 Pending: N (Backlog) · Highest priority: {ISSUE_ID} title (High)

⚠️ Needs attention: · {ISSUE_ID} has been in progress 3+ days with no PR — consider splitting? '''

---

Heartbeat Integration

Acceptance failure retry count storage: heartbeat-state.json → validation_retries.{ISSUE_ID}, max 3 attempts.

---

Error Handling

---

### HEARTBEAT.md · Section 1: Project Monitoring

```markdown
## 1. Project Monitoring (read PROJECTS.md, scan monitored repos)

**Each heartbeat executes A → B → C in order:**

---

### Step A: Linear Auto Task Check

**1. Query all `In Progress` + `Auto` label issues:**
'''bash
linear issue list --state "In Progress" --label "Auto" --json
'''

**2. For each Auto issue, check in sequence:**

**Timeout alert (no associated PR):**
In Progress > 3 days with no associated PR (branch name contains `{ISSUE_ID}`) → send:
`⏰ {ISSUE_ID} In Progress for N days, no PR seen`

**Acceptance fallback (AI complete but Gate not triggered):**
Check Linear comments for "Acceptance Report":
- Found → skip (Phase 4.5 already complete)
- Not found → read `heartbeat-state.json` `validation_retries.{ISSUE_ID}`
  - retries < 3 → trigger Phase 4.5 Acceptance Gate, retries +1, write back to state
  - retries ≥ 3 → skip (already escalated for human intervention, awaiting action)

**3. Concurrency control:** Count all In Progress Auto issues
- Count < 3 and Backlog has `Auto + Urgent/High` issue → move to Todo, send:
  `📅 {ISSUE_ID} auto-moved to Todo ({priority})`

---

### Step B: GitHub PR Scan

Read `heartbeat-state.json` `seen_prs` and `seen_merged_prs`:

'''python
monitored_repos = [
    "your-org/ProjectA",
    "your-org/ProjectB",
    # ...
]

for repo in monitored_repos:
    # 1. Open PR scan
    # gh pr list --repo {repo} --json number,title,createdAt,headRefName,statusCheckRollup
    for pr in open_prs:
        # New PR (not in seen_prs) → record, send notification, write to seen_prs
        # CI FAILURE → send immediately (ignore quiet hours)
        # Created > 24h still open → send review reminder (except quiet hours)

    # 2. Merged PR scan → Linear Done sync
    # gh pr list --repo {repo} --state merged --json number,title,mergedAt,headRefName
    for pr in merged_prs (not in seen_merged_prs):
        # Extract {ISSUE_ID} from branch name
        # → linear issue move {ISSUE_ID} --to "Done"
        # → send ✅ notification, record in seen_merged_prs
'''

---

### Step C: State Persistence

After each scan, write back to `heartbeat-state.json`:
'''json
{
  "seen_prs": { "your-org/ProjectA#12": "2026-03-19T10:00:00Z" },
  "seen_merged_prs": { "your-org/ProjectA#11": true },
  "validation_retries": { "PROJ-45": 1 }
}
'''

---

**Send conditions (send if any apply):**
- CI failure → send immediately (ignore quiet hours)
- New open PR / open > 24h without merge / acceptance fallback triggered / Auto task moved to Todo / In Progress > 3 days no PR → batch send (except quiet hours)

**Don't send:**
- No state changes
- 23:00–08:00 quiet hours (except CI failures)

**Send format:**
'''
🔔 Project Updates

[ProjectA] PR #12 "feat: plugin hot reload" waiting for review 25h
[ProjectB] CI failed: PR #5 "fix: crash on launch"
PROJ-45 In Progress 4 days, no PR seen
✅ PROJ-47 PR #8 merged → Linear Done
'''