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

13 KiB
Raw 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
  • Pattern-Key: clawteam.spawn_method
  • Recurrence-Count: 1
  • First-Seen: 2026-04-06
  • Last-Seen: 2026-04-06
Reference in New Issue View Git Blame Copy Permalink