Smartgift-AI/open-claw-team
17
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
open-claw-team/.openclaw/workspace/.learnings/LEARNINGS.md
T

16 KiB
Raw Permalink Blame History

Learnings Log

This file captures corrections, knowledge gaps, and best practices discovered during agent operation.

Format

Each entry:

## [LRN-YYYYMMDD-XXX] category

**Logged**: ISO-8601 timestamp
**Priority**: low | medium | high | critical
**Status**: pending | in_progress | resolved | wont_fix | promoted
**Area**: frontend | backend | infra | tests | docs | config

### Summary
One-line description

### Details
Full context

### Suggested Action
Specific improvement

### Metadata
- Source: conversation | error | user_feedback
- Related Files: path/to/file.ext
- Tags: tag1, tag2
- See Also: LRN-YYYYMMDD-XXX
- Pattern-Key: simplify.dead_code | harden.input_validation (optional)
- Recurrence-Count: 1
- First-Seen: YYYY-MM-DD
- Last-Seen: YYYY-MM-DD

---

Existing Learnings

[LRN-20260331-001] mandatory_skill_activation

Logged: 2026-03-31T02:26:00Z Priority: high Status: in_progress Area: orchestration

Summary

Always invoke using-superpowers skill before any response or action.

Details

User instruction: Skill using-superpowers must be activated at every interaction — startup, reset, tasks, ClawTeam usage, and chats.

Suggested Action

  • Before any task or response, read and apply using-superpowers skill
  • Treat it as mandatory, not optional
  • Check for applicable skills before any action

Metadata

  • Source: user_instruction
  • Related Files: skills/using-superpowers/SKILL.md
  • Tags: mandatory, skill_invocation
  • Pattern-Key: mandatory.skill_invocation
  • Recurrence-Count: 1
  • First-Seen: 2026-03-31
  • Last-Seen: 2026-03-31

[LRN-20260331-004] clawteam_self_then_peer_then_leader_review_workflow

Logged: 2026-03-31T09:54:00Z Priority: high Status: pending Area: orchestration

Summary

Enforce three-tier code review for ClawTeam workers: self-review → peer review → leader review.

Details

User-defined workflow for multi-agent code reviews in ClawTeam:

  1. Each worker must self-review their completed work before any peer review.
  2. Other workers then review the code.
  3. Finally, the leader (orchestrator) reviews and approves.

User provided detailed review prompt (modified for team context):

Review Prompt:

  • Plan Alignment Analysis: Compare against original planning doc; identify deviations; assess if justified improvements or problematic; verify all planned functionality implemented.
  • Code Quality Assessment: Check adherence to patterns/conventions; error handling, type safety, defensive programming; code organization, naming, maintainability; test coverage/quality; security/performance issues.
  • Architecture and Design Review: SOLID principles, architectural patterns; separation of concerns, loose coupling; integration with existing systems; scalability/extensibility.
  • Documentation and Standards: Appropriate comments/docs; file headers, function docs, inline comments accuracy; adherence to project coding standards.
  • Issue Identification and Recommendations: Categorize: Critical (must fix), Important (should fix), Suggestions (nice to have); provide specific examples and actionable recommendations; explain plan deviations (problematic vs beneficial); suggest improvements with code examples.
  • Communication Protocol: For significant deviations, ask coding agent to review/confirm; if plan issues, recommend plan updates; for implementation problems, provide clear guidance; always acknowledge strengths before issues.

This replaces ad-hoc review practices and ensures quality control in distributed development.

Suggested Action

  • Integrate this review workflow into clawteam-multi-agent-coordination skill guidance
  • Add prompts/checklists for each review tier (self, peer, leader)
  • Create automation or reminders to enforce the sequence
  • Document this as mandatory in AGENTS.md under ClawTeam workflows
  • Consider adding git hooks or task status transitions that gate peer/leader review until self-review is done

Metadata

  • Source: user_instruction
  • Related Files: skills/clawteam-multi-agent-coordination/SKILL.md, AGENTS.md
  • Tags: review, quality, multi-agent, workflow
  • Pattern-Key: orchestration.three_tier_review
  • Recurrence-Count: 1
  • First-Seen: 2026-03-31
  • Last-Seen: 2026-03-31

[LRN-20260331-003] use_clawteam_cli_not_session_spawn

Logged: 2026-03-31T09:48:00Z Priority: high Status: pending Area: infra

Summary

Never use sessions_spawn for multi-agent coordination; always use ClawTeam CLI (clawteam-multi-agent-coordination skill).

Details

User instruction: For any multi-agent work (creating teams, spawning agents, assigning tasks, monitoring progress), do NOT use OpenClaw's session spawn mechanism (sessions_spawn, subagents). Instead, always use the ClawTeam CLI following the clawteam-multi-agent-coordination skill. This ensures proper task management, git worktree isolation, agent messaging, kanban board, and recovery tooling.

Suggested Action

  • When multi-agent coordination is needed, invoke clawteam-multi-agent-coordination skill first
  • Use clawteam commands: spawn-team, task create, spawn, board show/attach, inbox send/receive, workspace merge
  • Update AGENTS.md to explicitly state: "For tasks requiring multiple agents, use ClawTeam CLI; avoid sessions_spawn/subagents for coordination"
  • Remove/replace any existing patterns that use subagents for parallel work

Metadata

  • Source: user_instruction
  • Related Files: skills/clawteam-multi-agent-coordination/SKILL.md, AGENTS.md
  • Tags: multi-agent, clawteam, sessions_spawn, best_practice
  • Pattern-Key: orchestration.clawteam_over_subagents
  • Recurrence-Count: 1
  • First-Seen: 2026-03-31
  • Last-Seen: 2026-03-31

[LRN-20260331-002] production_ready_not_mvp

Logged: 2026-03-31T02:50:00Z Priority: critical Status: in_progress Area: orchestration

Summary

All projects must deliver production-ready, polished products, not barebones MVP.

Details

User explicitly stated: "với mọi dự án thì tôi đều muốn mọi thứ (kết quả) phải thật hoàn thiện, ra được product thật và có thể sử dụng thật chứ không phải bản MVP sơ sài". This is a core quality standard: no quick-and-dirty implementations, no "good enough for now" shortcuts. Every deliverable should be fully functional, responsive, accessible, error-handled, and deployable.

Suggested Action

  • In planning phase, define acceptance criteria as "production-ready" features (responsive design, error handling, testing, accessibility, SEO, performance)
  • During implementation, include polish tasks (animations, hover states, mobile layouts, form validation, loading states)
  • Before marking complete, run verification checks (build success, no console errors, responsive test, accessibility audit)
  • Avoid technical debt shortcuts; invest in clean architecture and maintainable code from the start
  • In code reviews, check for completeness, not just functionality

Metadata

  • Source: user_instruction
  • Related Files: docs/superpowers/plans/*.md
  • Tags: quality, production-ready, no-mvp
  • Pattern-Key: quality.standard.production_ready
  • Recurrence-Count: 1
  • First-Seen: 2026-03-31
  • Last-Seen: 2026-03-31

New Learnings — 2026-04-06 (ClawTeam Templates & Dev Team Expansion)

[LRN-20260406-001] use_clawteam_templates_for_team_creation

Logged: 2026-04-06T07:25:00Z Priority: high Status: resolved Area: orchestration

Summary

When a requested team type doesn't exist, first check ~/.clawteam/templates/ for a matching template before creating a team from scratch.

Details

User instruction: If dev-team (or any team type) doesn't exist, look in ~/.clawteam/templates/ directory first. Templates provide pre-configured roles, tasks, and worker instructions. Available templates:

  • dev-team.toml — Tech Lead + Full-stack + Frontend + Backend + UX/UI
  • qc-team.toml — QC Lead + Code Reviewer + Test Engineer + Acceptance Auditor

Before spawning any team, run ls ~/.clawteam/templates/ to see what's available. If template exists, use it as the base configuration.

Suggested Action

  • Always check ~/.clawteam/templates/ when user requests team creation
  • If template exists, use it (modify if needed)
  • If no template exists, create one from scratch and save to templates for future reuse

Metadata

  • Source: user_instruction
  • Related Files: ~/.clawteam/templates/dev-team.toml, ~/.clawteam/templates/qc-team.toml
  • Tags: clawteam, templates, team-creation
  • Pattern-Key: orchestration.use_templates_for_teams
  • Recurrence-Count: 1
  • First-Seen: 2026-04-06

[LRN-20260406-002] dev_team_includes_qc_and_devops

Logged: 2026-04-06T07:30:00Z Priority: high Status: resolved Area: orchestration

Summary

Dev team must include QC (Quality Control) and DevOps roles. Updated dev-team.toml template to add qc-lead, qa-engineer, and devops-engineer agents.

Details

User explicitly requested adding 1 QC and 1 DevOps to the dev-team template. Updated ~/.clawteam/templates/dev-team.toml with:

  • qc-lead — Code quality gate, review coordination, acceptance criteria
  • qa-engineer — Test coverage, TDD compliance, edge case validation, regression tests
  • devops-engineer — CI/CD, Docker, deployment, monitoring, infrastructure

Also added initial tasks for QC (quality criteria definition) and DevOps (CI pipeline setup).

Suggested Action

  • When spawning dev teams, always include QC and DevOps members
  • QC runs after feature implementation (dependent tasks)
  • DevOps works in parallel for CI/CD setup early

Metadata

  • Source: user_instruction
  • Related Files: ~/.clawteam/templates/dev-team.toml
  • Tags: clawteam, team-structure, qc, devops
  • Pattern-Key: orchestration.dev_team_with_qc_devops
  • Recurrence-Count: 1
  • First-Seen: 2026-04-06

New Learnings — 2026-04-03 (ClawTeam Deep Dive)

[LRN-20260403-001] no_sessions_spawn_for_multi_agent

Logged: 2026-04-03T09:30:00Z Priority: critical Status: resolved Area: orchestration

Summary

NEVER use sessions_spawn for multi-agent coordination. ALWAYS use clawteam CLI.

Suggested Action

  • Never call sessions_spawn for multi-agent work
  • If used by mistake → immediately kill and redo with clawteam

Metadata

  • Source: user_correction
  • Related Files: AGENTS.md, RULES.md
  • Tags: clawteam, orchestration, sessions_spawn
  • Pattern-Key: clawteam.no_subagent
  • Recurrence-Count: 3
  • First-Seen: 2026-04-03

[LRN-20260406-003] strict_quality_gate_and_template_usage

Logged: 2026-04-06T08:04:00Z Priority: critical Status: resolved Area: orchestration

Summary

PM must enforce strict quality standards using templates and zero-tolerance policy; all teams must use templates from ~/.clawteam/templates/.

Details

User explicitly required: khi review code thì phải cực kỳ khắt khe, phải đạt mọi tiêu chuẩn cao, không để tasks/projects không đạt chất lượng. Added comprehensive strict quality checklist to RULES.md and enhanced AGENTS.md with enforcement note. Also ensured dev and QC team templates use PM role and include QC/DevOps.

Suggested Action

  • PMs must verify all tasks independently (read diff, run tests, check coverage)
  • Use the strict checklist; reject any non-compliance
  • Always check templates directory when creating teams
  • No task may complete unless ALL criteria passed

Metadata

  • Source: user_instruction
  • Related Files: RULES.md, AGENTS.md, ~/.clawteam/templates/dev-team.toml, ~/.clawteam/templates/qc-team.toml
  • Tags: quality, strict, template, review
  • Pattern-Key: orchestration.strict_quality_gate
  • Recurrence-Count: 1
  • First-Seen: 2026-04-06
  • Last-Seen: 2026-04-06

[LRN-20260406-001] clawteam_spawn_method

Logged: 2026-04-06T10:10:00Z Priority: critical Status: resolved Area: orchestration

Summary

Never use subprocess for spawning agents. Always use clawteam spawn tmux openclaw --team <team> --agent-name <name> --agent-type <type> --task "<task>".

Details

When spawning ClawTeam agents, using clawteam spawn subprocess openclaw causes agents to die immediately after the subprocess shell exits. This resulted in:

  • All 12 agents spawning but dying instantly
  • 75 tasks all remaining pending with 0 in_progress because no one was alive to work
  • Tasks falsely marked completed (only directory copying happened, not actual development)
  • Zero dependency tracking (all tasks independent despite clear ordering requirements)
  • Complete project management failure

Suggested Action

  • ALWAYS use clawteam spawn tmux openclaw --team <team> --agent-name <name> ... for persistent agent sessions
  • NEVER use clawteam spawn subprocess — it exits immediately after the shell terminates
  • Verify agents are alive: tmux list-sessions | grep clawteam
  • Check task progress: clawteam task list <team> --status in_progress
  • Set task dependencies with clawteam task update <team> <id> --add-blocked-by <dep-id>
  • Monitor progress: clawteam board attach <team>

Metadata

  • Source: error
  • Tags: clawteam, spawn, subprocess, orchestration, critical

Metadata

  • Source: error
  • Tags: clawteam, spawn, subprocess, orchestration, critical
  • Pattern-Key: clawteam.spawn_method
  • Recurrence-Count: 1
  • First-Seen: 2026-04-06
  • Last-Seen: 2026-04-06

[LRN-20260407-001] continuous_clawteam_monitoring_and_quality_control

Logged: 2026-04-07T07:07:00Z Priority: critical Status: in_progress Area: orchestration/quality-control

Summary

Continuous monitoring of ClawTeam progress and quality gates is mandatory to catch issues early and maintain consistent high-quality output.

Details

User instruction: When ClawTeam is running, I must continuously monitor progress and check for specific quality control issues:

Task Status Issues:

  • Blocked tasks that are not unblocked (stuck indefinitely)
  • Tasks stuck in pending without moving to in_progress
  • Tasks marked in_progress but not actually working (agents idle or unresponsive)
  • Tasks not blocked but still pending (missing dependencies or abandoned)

Agent Interaction & Review Issues:

  • Agents not communicating with each other (lack of inbox usage)
  • Agents not doing self-review before reporting completion
  • Agents not doing peer review (skipping peer feedback stage)
  • Project manager not reviewing tasks (bypassing Tier 3 quality gate)

This is a proactive oversight requirement, not a reactive one. We must regularly check (multiple times per day during active team operations) to catch these issues before they cascade. The goal is to ensure consistent quality and prevent substandard work from completing.

Suggested Action

Establish a monitoring cadence and checklist for active ClawTeam projects:

  1. Regular Check Schedule

    • Check team boards every 2-4 hours during active work periods
    • More frequent (hourly) for tight deadlines / high-velocity teams
    • Less frequent (twice daily) for low-velocity / planning phases

  2. Monitoring Checklist

    • Review board: identify any blocked tasks not recently unblocked
    • Check pending tasks: are old tasks stuck? Verify dependencies are set correctly
    • Check in_progress tasks: are agents actually active? Use clawteam context log to see recent activity
    • Verify inbox flow: are agents sending/receiving messages? Look for unanswered messages
    • Review task transitions: ensure completed tasks went through needs-self-review → needs-peer-review → needs-leader-review
    • Spot-check code: for tasks marked completed, verify worker did self-review, peer review occurred, and leader approval given

  3. Automation/Aids

    • Create a script or alias to run quick checks: clawteam board show <team> + clawteam task list <team> --status blocked + clawteam task list <team> --status in_progress
    • Set reminders during active development sprints
    • Use clawteam context conflicts to detect worktree issues

  4. Intervention Protocol

    • If an agent is idle (in_progress but no activity for >2h), send inbox message to check status
    • If blocked task not unblocked, contact PM/leader to resolve
    • If reviews skipped, request immediate self/peer review before allowing task to advance
    • Document recurring issues in learnings to improve agent prompts/team setup

Metadata

  • Source: user_instruction
  • Tags: clawteam, monitoring, quality-gate, recurring-check, orchestration
  • Pattern-Key: orchestration.continuous_monitoring
  • Recurrence-Count: ongoing (recurring check)
  • First-Seen: 2026-04-07
  • Last-Seen: 2026-04-07
Reference in New Issue View Git Blame Copy Permalink