arka/librefang-registry
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(hands): add devteam hand (#41)

Browse Source 
* feat(hands): add devteam hand -- autonomous software development team

Multi-agent hand with 7 roles (PM, Architect, Frontend, Backend, DevOps, QA, Designer)
and 3 team size tiers (simple/standard/full) for different project scales.

PM coordinator auto-scans GitHub issues, triages, assigns tasks to specialists,
and tracks progress on an in-memory project board.

* refactor(hands): slim devteam to 3 agents (PM + Engineer + QA)

7 agents with serial agent_send = massive token waste and info loss at every
handoff. Merge architect/frontend/backend/devops into one Engineer with full
context. Keep QA separate for independent verification. Drop designer.

Tiers: lite (PM + Engineer) and standard (PM + Engineer + QA).

* fix(hands/devteam): fix workspace isolation and git workflow gaps

- PM uses GitHub API for code browsing, no repo clone needed
- Engineer explicitly clones repo, branches, commits, pushes, creates PR
- QA explicitly clones repo, checks out branch under review
- PM tracks last_scan timestamp to filter already-triaged issues
- approval_mode now means PR stays open for review, not skip commit

* fix(hands/devteam): use shared repo checkout instead of per-agent clones

All 3 agents share one checkout at ../shared/repo/. Engineer clones it
on the first task; PM and QA read from the same path. Eliminates
duplicate clones and cross-workspace visibility issues.

* fix(hands/devteam): read issue comments before triaging

Comments contain clarifications, reproduction steps, duplicate markers,
and resolution status. Also skip already-assigned and wontfix issues.

* fix(hands/devteam): fix interactive git add, add merge/close APIs, add fix iteration flow

- Replace git add -p (interactive) with git add <specific files>
- PM prompt now has explicit merge PR and close issue API calls
- Engineer has explicit fix-request handling (same branch, push, no new PR)

* feat(hands/devteam): add full GitHub interaction -- PR review, issue comments, labels

PM:
- Labels issues during triage, comments triage status
- Scans open PRs for external review requests
- Comments on issues linking merged PRs

Engineer:
- Replies to review comments on PR after fixing
- Reviews external PRs with APPROVE/REQUEST_CHANGES + line comments

QA:
- Leaves PR review (APPROVE or REQUEST_CHANGES with line comments)
- All findings visible on GitHub, not just via agent_send

SKILL.md:
- Added PR diff, reviews, review comments, reply, merge API references

* fix(hands/devteam): enforce English comments, line-level reviews, comment-before-close

- All GitHub comments/reviews must be in English (added global rule)
- PR reviews must use comments[] with path+line, not body-only
- Comment on issue with resolution details BEFORE closing/merging
- Improved comment templates with structured info

* fix(hands/devteam): 8 logic fixes from end-to-end workflow review

1. Filter PRs from Issues API (pull_request key)
2. PM sends PR number to QA for review
3. Deduplicate PR scanning via devteam_reviewed_prs
4. QA reports test gaps instead of pushing code to shared branch
5. branch_strategy wired into Engineer (gitflow branches from develop)
6. approval_mode: ON = wait for human, OFF = auto-merge after QA
7. scan_interval mapped to schedule_create every_secs
8. git checkout -B instead of -b to handle existing branches

* fix(hands/devteam): second-pass review — 6 more logic fixes

1. Engineer extracts PR number from create-PR API response
2. PM falls back to GitHub Contents API when shared repo not yet cloned
3. QA gets external PR review flow (was only on Engineer)
4. PM checks CI status + mergeable before merging
5. PM handles merge conflict (409) by sending back to Engineer to rebase
6. i18n approval_mode description synced with actual semantics

* fix(hands/devteam): third-pass — runtime scenarios

1. Deduplicate cron schedule on daemon restart (check schedule_list first)
2. Max 3 review rounds before escalating to user (prevent infinite loop)
3. Clean working directory before switching tasks (git checkout -- . && git clean)
4. Add user direct commands (work on #42, status, review PR #50)
5. Pass tech_stack to Engineer in task delegation
6. Fix duplicate step numbering in Review Cycle

* fix(hands/devteam): fourth-pass — state consistency and edge cases

1. QA force-syncs to remote branch (git checkout -B origin/branch) for force-push safety
2. Board sync step: reconcile with GitHub each scan cycle (catch external closes/merges)
3. Prune devteam_reviewed_prs of closed PRs, cap done list at 30
4. PM checks CI before sending to QA (don't waste QA on red builds)
5. Stop/cancel command: remove from board, comment on issue
6. Explicit rebase commands for Engineer (fetch + rebase + force-with-lease)

* fix(hands/devteam): fifth-pass — crash prevention

1. Guard empty repo_url: stop and tell user to configure it
2. Add python3 to requires (all JSON parsing depends on it)
3. Engineer git config user.name/email on first clone (prevents commit rejection)
4. Explicit build/lint/test commands per tech stack (Rust/TS/Python/Go/Java/Swift)
5. event_publish on task completion so user gets notified
6. Global rule: check API HTTP status before parsing JSON

* feat(hands/devteam): add gh CLI / MCP / curl API three-layer fallback

- Add GitHub MCP integration (mcp_servers = ["github"])
- Add gh CLI as optional requirement (preferred over curl)
- All 3 agents: gh > MCP > curl priority for GitHub operations
- Add issue_tracker setting (github/linear/jira)
- Add agent_list to shared tools
- SKILL.md: add full gh CLI reference section
- i18n: add issue_tracker translation

* feat(hands/devteam): full MCP/integration/notification layer

MCP allowlist: github, linear, jira, sentry, slack, discord
- Sentry: Engineer reads crash reports/stack traces when fixing bugs
- Slack/Discord: PM posts status updates (triaged, completed, QA results)
- Linear/Jira: alternative issue trackers

New settings: notify_channel (none/slack/discord), issue_tracker (github/linear/jira)
New optional requires: npx (MCP runtime), SENTRY_AUTH_TOKEN

PM prompt: notification section, channel-aware status posting
Engineer prompt: Sentry context lookup for bug fixes
i18n: added translations for new settings

* feat(hands/devteam): workflows, onboarding, knowledge, standup, rollback

Workflows (8 integrated):
- PM: bug-triage, product-spec, weekly-report, incident-postmortem
- Engineer: code-review, test-generation, refactor-plan, api-design
- QA: code-review, test-generation

New capabilities:
- Repo onboarding: first activation analyzes repo structure/stack/CI
- Knowledge accumulation: store lessons per issue, detect module hotspots
- Daily standup: cron schedule, board summary via notify_channel
- Rollback: gh pr revert + postmortem workflow + re-open issue

Also:
- Added workflow_run to tools, skills = [] (all allowed)
- Rewrote README with full architecture, lifecycle, workflow table
- PM prompt now has 15 sections covering full lifecycle

* feat(hands/devteam): per-agent capabilities, resources, profiles, fallbacks

Each agent now has full AgentManifest config (not just system_prompt):

PM:
- profile: automation
- capabilities: web, memory, schedule, knowledge, event, workflow, agent_send
- shell: gh, curl, cat, python3
- resources: 200k tokens/hr

Engineer:
- profile: coding
- capabilities: file r/w, shell, web, memory, knowledge, workflow
- shell: cargo, npm, python, go, swift, mvn, git, gh, docker, make
- resources: 300k tokens/hr, 10 concurrent tools
- network: * (needs to push to GitHub)

QA:
- profile: coding (read-heavy, no file_write)
- capabilities: file read, shell (test/lint commands only), web, workflow
- shell: cargo test/clippy/audit, npm test, pytest, go test, gh
- resources: 150k tokens/hr

All agents have fallback_models configured.

* feat(hands/devteam): rewrite with proper resource composition

First hand to use the new composition features:

Agents:
- PM: base=planner, capabilities restricted to gh/git shell only
- Engineer: base=coder, full shell access, network=*
- QA: base=code-reviewer, tool_blocklist=[file_write], test/lint shells only

Composition:
- base: inherit from agents/planner, agents/coder, agents/code-reviewer
- mcp_servers: github (agents interact via MCP, not curl in prompts)
- workflows: bug-triage, code-review, test-generation via workflow_run tool
- plugins: todo-tracker, auto-summarizer, episodic-memory
- per-agent skills: SKILL-pm.md, SKILL-engineer.md, SKILL-qa.md
- per-agent capabilities: QA can't write files, PM can't run builds

Prompts are clean and focused (role + methodology + principles),
not stuffed with curl commands. GitHub interaction goes through
MCP tools or gh CLI.

* fix(devteam): complete planner methodology in PM prompt

Added SCOPE/SEQUENCE/RISK/MILESTONE keywords from the planner
base template's methodology into the PM's triage workflow.

* docs: update hands README, fix repo_url reference in prompts

- hands/README.md: document full composition model (base, MCP, workflows,
  plugins, per-agent skills, per-agent capabilities)
- Updated hand count to 15 (added devteam)
- Engineer prompt: clarify repo_url comes from User Configuration, not
  a template variable
- PM prompt: same clarification

* fix(devteam): override name/description from base templates

Without explicit name, agents inherit base names (planner/coder/code-reviewer)
instead of hand-specific names (pm/engineer/qa). This affects display and
the prefixed name used in agent registry (devteam:pm vs devteam:planner).

* style: format HAND.toml with taplo
This commit is contained in:
Evan authored and GitHub committed 2026-04-10 10:24:26 +08:00
1 parent b567db71ba
commit 2b8259a0c0
6 files changed
+738 -59
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

hands/README.md
+95 -59
View File
@@ -1,94 +1,130 @@
# Hands # Hands
Hand definitions for LibreFang. Hands are the user-facing "apps" -- higher-level application bundles that package an agent with tools, settings, dashboard metrics, and dependency requirements. Hand definitions for LibreFang. Hands are pre-packaged capability bundles that compose **agents**, **tools**, **skills**, **MCP servers**, **workflows**, and **plugins** into a working application.
> "You have many hands helping you." -- Hands are how LibreFang users interact with specialized capabilities. > "You have many hands helping you."
## Structure ## Structure
``` ```
hands/ hands/
├── devteam/
│ ├── HAND.toml # Hand definition
│ ├── SKILL-pm.md # Per-agent reference knowledge (PM)
│ ├── SKILL-engineer.md # Per-agent reference knowledge (Engineer)
│ └── SKILL-qa.md # Per-agent reference knowledge (QA)
├── browser/ ├── browser/
│ ├── HAND.toml # Hand definition
│ └── SKILL.md # Expert knowledge for the agent
├── trader/
│ ├── HAND.toml │ ├── HAND.toml
│ └── SKILL.md │ └── SKILL.md # Shared reference knowledge (all agents)
└── ... └── ...
``` ```
## Composition Model
A hand composes registry resources — it doesn't reinvent them:
| Resource | How to compose | Example |
|----------|----------------|---------|
| **Agent templates** | `base = "coder"` on `[agents.*]` | Inherit prompt, model config, fallbacks from `agents/coder/agent.toml` |
| **Tools** | `tools = [...]` at hand level | All agents get these built-in tools |
| **Skills** | `skills = [...]` at hand level | Skill allowlist (empty = all) |
| **MCP servers** | `mcp_servers = [...]` at hand level | Agent interacts via MCP tools, not hardcoded API calls |
| **Workflows** | `workflow_run` tool in agent prompts | Agent calls `workflow_run bug-triage` at runtime |
| **Plugins** | `allowed_plugins = [...]` at hand level | Plugin allowlist (empty = all) |
| **Per-agent skills** | `SKILL-{role}.md` files | Different reference knowledge per agent role |
| **Per-agent capabilities** | `[agents.*.capabilities]` | Fine-grained shell/network/memory per agent |
## HAND.toml Format ## HAND.toml Format
```toml ```toml
id = "hand-id" # Must match directory name id = "hand-id"
name = "Hand Name" name = "Hand Name"
description = "What this hand does" description = "What this hand does"
category = "productivity" # communication | content | data | development | category = "development"
# devops | finance | productivity | research | social
icon = "🔧" icon = "🔧"
tools = ["tool1", "tool2"]
# ─── Resource composition ────────────────────────────────────
tools = ["shell_exec", "file_read", "web_fetch", "workflow_run"]
mcp_servers = ["github", "sentry"]
skills = [] # empty = all
allowed_plugins = ["todo-tracker"]
# ─── Requirements ────────────────────────────────────────────
[[requires]]
key = "git"
requirement_type = "binary"
check_value = "git"
# ─── Settings ────────────────────────────────────────────────
[[settings]]
key = "repo_url"
setting_type = "text"
default = ""
# ─── Agents ──────────────────────────────────────────────────
# Multi-agent with base template inheritance:
[agents.main]
coordinator = true
base = "planner" # inherits from agents/planner/agent.toml
invoke_hint = "Task coordination"
[agents.main.model]
system_prompt = """Custom prompt for this hand..."""
[agents.main.capabilities]
shell = ["gh *", "git *"] # preserved by kernel (not overwritten)
# Single-agent (legacy):
# [agent]
# name = "my-agent"
# system_prompt = """..."""
# ─── Routing ─────────────────────────────────────────────────
[routing] [routing]
aliases = ["activate phrases"] aliases = ["activate phrases"]
weak_aliases = ["keyword hints"] weak_aliases = ["keyword hints"]
[[requires]] # External dependencies # ─── Dashboard ───────────────────────────────────────────────
key = "python3" [dashboard]
requirement_type = "binary"
check_value = "python3"
[[settings]] # User-configurable options
key = "headless"
setting_type = "toggle"
default = "true"
[agent] # The agent powering this hand
name = "hand-agent"
module = "builtin:chat"
system_prompt = """..."""
# Optional: i18n for name, description, category, and settings
# Supported languages: zh, ja, ko, es, fr, de
[i18n.zh]
name = "浏览器 Hand"
description = "自主网页浏览器"
category = "生产力"
[i18n.zh.settings.headless] # Per-setting label/description translation
label = "无头模式"
description = "在后台运行浏览器"
[dashboard] # Dashboard metrics
[[dashboard.metrics]] [[dashboard.metrics]]
label = "Tasks Completed" label = "Tasks Done"
memory_key = "metric_key" memory_key = "metric_key"
format = "number" format = "number"
# ─── i18n ────────────────────────────────────────────────────
[i18n.zh]
name = "中文名"
description = "中文描述"
``` ```
## Current Hands (14) ## Current Hands (15)
| Hand | Category | Description | | Hand | Category | Agents | Description |
|------|----------|-------------| |------|----------|--------|-------------|
| analytics | data | Data analytics, visualization, dashboards, and automated reporting | | analytics | data | multi | Data analytics, visualization, and automated reporting |
| apitester | development | API testing, endpoint discovery, load testing, and regression detection | | apitester | development | single | API testing, endpoint discovery, and load testing |
| browser | productivity | Web navigation, form filling, and multi-step web tasks | | browser | productivity | single | Web navigation, form filling, and multi-step web tasks |
| clip | content | Turns long-form video into short clips with captions and thumbnails | | clip | content | multi | Long-form video to short clips with captions |
| collector | data | Intelligence collection, change detection, and knowledge graphs | | collector | data | multi | Intelligence collection and change detection |
| devops | development | CI/CD management, infrastructure monitoring, and incident response | | **devteam** | **development** | **multi** | **Autonomous dev team — PM + Engineer + QA with base templates** |
| lead | data | Lead generation, enrichment, scoring, and scheduled delivery | | devops | development | multi | CI/CD management, monitoring, and incident response |
| linkedin | communication | LinkedIn content creation, networking, and engagement | | lead | data | multi | Lead generation, enrichment, and scoring |
| predictor | data | Signal collection, calibrated predictions, and accuracy tracking | | linkedin | communication | multi | LinkedIn content creation and networking |
| reddit | communication | Subreddit monitoring, content posting, and engagement tracking | | predictor | data | single | Signal collection and calibrated predictions |
| researcher | productivity | Deep research, cross-referencing, fact-checking, and reports | | reddit | communication | multi | Subreddit monitoring and content posting |
| strategist | productivity | Market research, competitive analysis, and strategic planning | | researcher | productivity | multi | Deep research, fact-checking, and reports |
| trader | data | Market intelligence, multi-signal analysis, and risk management | | strategist | productivity | multi | Market research and competitive analysis |
| twitter | communication | Twitter/X content creation, scheduling, and performance tracking | | trader | data | multi | Market intelligence and risk management |
| twitter | communication | multi | Twitter/X content creation and scheduling |
## Adding a New Hand ## Adding a New Hand
1. Create `hands/<name>/HAND.toml` and `SKILL.md` (expert knowledge for the agent) 1. Create `hands/<name>/HAND.toml`
2. Ensure `id` matches the directory name 2. Add `SKILL.md` (shared) or `SKILL-{role}.md` (per-agent) for reference knowledge
3. Run `python scripts/validate.py` 3. Use `base = "agent-name"` to inherit from existing agent templates in `agents/`
4. Submit a PR 4. Set `mcp_servers`, `skills`, `allowed_plugins` for resource composition
5. Ensure `id` matches the directory name
6. Submit a PR
See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full guide. See [CONTRIBUTING.md](../CONTRIBUTING.md) for the full guide.
hands/devteam/HAND.toml
+397
View File
@@ -0,0 +1,397 @@
id = "devteam"
version = "1.0.0"
name = "Dev Team"
description = "Autonomous software development team — PM triages issues, Engineer implements, QA validates"
category = "development"
icon = "🏗"
# ─── Hand-level resource composition ─────────────────────────────────────────
# Tools available to ALL agents (kernel overrides per-agent capabilities.tools)
tools = [
"shell_exec",
"file_read",
"file_write",
"file_list",
"web_fetch",
"web_search",
"memory_store",
"memory_recall",
"memory_list",
"schedule_create",
"schedule_list",
"schedule_delete",
"knowledge_add_entity",
"knowledge_add_relation",
"knowledge_query",
"event_publish",
"agent_list",
"workflow_run",
]
# MCP servers: all agents can access these (per-agent mcp_servers further restricts)
mcp_servers = ["github"]
# Skills: all available (agents can restrict individually)
skills = []
# Plugins: useful for dev workflow
allowed_plugins = ["todo-tracker", "auto-summarizer", "episodic-memory"]
# ─── Requirements ────────────────────────────────────────────────────────────
[[requires]]
key = "git"
label = "git"
requirement_type = "binary"
check_value = "git"
[requires.install]
macos = "brew install git"
linux_apt = "sudo apt install git"
[[requires]]
key = "gh"
label = "GitHub CLI (preferred for GitHub operations)"
requirement_type = "binary"
check_value = "gh"
optional = true
[requires.install]
macos = "brew install gh"
linux_apt = "sudo apt install gh"
manual_url = "https://cli.github.com/"
[[requires]]
key = "GITHUB_TOKEN"
label = "GitHub Token"
requirement_type = "api_key"
check_value = "GITHUB_TOKEN"
[requires.install]
signup_url = "https://github.com/settings/tokens"
env_example = "GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
steps = [
"Go to GitHub Settings → Developer settings → Fine-grained tokens",
"Grant: Issues (read/write), Pull requests (read/write), Contents (read/write)",
"Set as GITHUB_TOKEN environment variable",
]
# ─── Routing ─────────────────────────────────────────────────────────────────
[routing]
aliases = [
"dev team",
"development team",
"software team",
"build a project",
"issue triage",
]
weak_aliases = ["project management", "sprint", "kanban", "implement feature"]
# ─── Settings ────────────────────────────────────────────────────────────────
[[settings]]
key = "team_size"
label = "Team Size"
description = "Lite = PM + Engineer (PM handles QA). Standard = PM + Engineer + QA."
setting_type = "select"
default = "standard"
[[settings.options]]
value = "lite"
label = "Lite (PM + Engineer)"
[[settings.options]]
value = "standard"
label = "Standard (PM + Engineer + QA)"
[[settings]]
key = "repo_url"
label = "Repository"
description = "GitHub repository (owner/repo)"
setting_type = "text"
default = ""
[[settings]]
key = "scan_interval"
label = "Issue Scan Interval"
setting_type = "select"
default = "15min"
[[settings.options]]
value = "5min"
label = "Every 5 minutes"
[[settings.options]]
value = "15min"
label = "Every 15 minutes"
[[settings.options]]
value = "1hour"
label = "Every hour"
[[settings.options]]
value = "manual"
label = "Manual only"
[[settings]]
key = "approval_mode"
label = "Approval Mode"
description = "ON = PM waits for human approval before merging. OFF = auto-merge after QA passes."
setting_type = "toggle"
default = "true"
# ─── Agents ──────────────────────────────────────────────────────────────────
# Each agent uses `base` to inherit from a registry agent template.
# Only hand-specific overrides are defined here.
[agents.pm]
coordinator = true
base = "planner"
name = "pm"
description = "Product Manager — triages issues, assigns tasks, tracks progress"
invoke_hint = "Issue triage, task assignment, progress tracking, status reports, rollback coordination"
[agents.pm.model]
max_tokens = 8192
temperature = 0.3
system_prompt = """You are the PM of an autonomous dev team. You coordinate, you do NOT write code.
## Team
Read **User Configuration** for team_size:
- **Lite**: You + Engineer. You handle QA (review PR diffs, verify acceptance criteria).
- **Standard**: You + Engineer + QA. Delegate implementation to Engineer, verification to QA.
## Repo
All agents share one checkout at `../shared/repo/`. Engineer clones it. You read from it or use GitHub MCP/gh CLI.
Read the **Repository** value from **User Configuration** (injected below). If empty, tell the user to configure it and stop.
## Workflow
1. **Startup**: memory_recall devteam_board, create scan schedule (5min=300s, 15min=900s, 1hour=3600s) if not exists
2. **Scan**: Use GitHub MCP tools to list open issues (filter out PRs). Read comments. Skip assigned/wontfix/duplicate.
3. **Triage** (Planner methodology — SCOPE, DECOMPOSE, SEQUENCE, ESTIMATE, RISK, MILESTONE):
- SCOPE: what's in/out for this issue
- Classify (bug/feature/refactor), ESTIMATE size (S/M/L/XL)
- For XL: DECOMPOSE into sub-issues, SEQUENCE by dependencies, identify RISK, set MILESTONEs. Use workflow_run product-spec for vague features.
- Label, comment (English)
4. **Delegate**: Send Engineer issue #, acceptance criteria, branch name, tech stack. Use workflow_run bug-triage for complex bugs.
5. **Review**: Check CI first. Send to QA (standard) or review yourself (lite). Max 3 rounds before escalating to user.
6. **Merge**: If approval_mode ON, wait for user. Check mergeable. Comment on issue. Merge. Close.
7. **Knowledge**: After each resolve, knowledge_add_entity for the fix. Flag modules with 3+ bugs as hotspots.
8. **Standup**: Daily summary via event_publish.
9. **Rollback**: On regression report, revert PR, re-open issue, workflow_run incident-postmortem.
## Rules
- All GitHub comments/reviews in English.
- Max 2 concurrent tasks for Engineer.
- Never close without verification.
- Prioritize: production bugs > regressions > features > tech debt.
"""
[agents.pm.capabilities]
agent_message = ["*"]
memory_read = ["*"]
memory_write = ["self.*", "shared.*"]
shell = ["gh *", "git *"]
[agents.pm.resources]
max_llm_tokens_per_hour = 200000
[agents.engineer]
base = "coder"
name = "engineer"
description = "Full-stack Engineer — designs, implements, tests, handles CI/CD"
invoke_hint = "Code implementation, bug fixing, architecture, CI/CD, tests"
[agents.engineer.model]
max_tokens = 16384
temperature = 0.2
system_prompt = """You are the Engineer of an autonomous dev team. Senior full-stack developer.
## Repo
All agents share `../shared/repo/`. You own it — clone on first task.
Read the **Repository** value from **User Configuration** (injected below your prompt) and substitute it in commands. Example for owner/repo:
```bash
REPO_DIR="../shared/repo"
[ ! -d "$REPO_DIR" ] && mkdir -p ../shared && git clone "https://x-access-token:$GITHUB_TOKEN@github.com/OWNER/REPO.git" "$REPO_DIR" && cd "$REPO_DIR" && git config user.name "DevTeam Hand" && git config user.email "devteam@librefang.ai"
cd "$REPO_DIR" && git checkout -- . 2>/dev/null; git clean -fd 2>/dev/null; git checkout main && git pull
```
## Methodology (inherited from Coder agent)
READ → PLAN → IMPLEMENT → TEST → VERIFY
## Workflow
1. Receive task from PM with issue #, acceptance criteria, branch name
2. Create branch: `git checkout -B {branch} main`
3. Read code, understand context
4. For L/XL: send design to PM for alignment first
5. Implement + write tests
6. Run build/lint/test for the detected stack
7. Commit specific files, push, create PR via GitHub MCP or gh CLI
8. Report to PM: branch, PR #, files changed, build status
## Fix Requests
Same branch. Fix. Push. Reply on PR in English. If rebase needed: `git fetch origin && git rebase origin/main && git push --force-with-lease`
## Workflows
- workflow_run test-generation: when adding test coverage
- workflow_run code-review: for external PR reviews
- workflow_run refactor-plan: for refactoring tasks
- workflow_run api-design: for new API endpoints
## Knowledge
After each task: knowledge_add_entity for what was done and why.
Before each task: knowledge_query for the affected module.
"""
[agents.engineer.capabilities]
network = ["*"]
memory_read = ["*"]
memory_write = ["self.*", "shared.*"]
shell = [
"cargo *",
"rustc *",
"npm *",
"node *",
"python *",
"pip *",
"go *",
"swift *",
"mvn *",
"git *",
"gh *",
"make *",
"docker *",
]
[agents.engineer.resources]
max_llm_tokens_per_hour = 300000
[agents.qa]
base = "code-reviewer"
name = "qa"
description = "QA Engineer — reviews code, runs tests, catches bugs"
invoke_hint = "Code review, testing, quality verification, security audit"
# QA can't modify code — only read and verify
tool_blocklist = ["file_write"]
[agents.qa.model]
max_tokens = 8192
temperature = 0.2
system_prompt = """You are the QA Engineer of an autonomous dev team. Be skeptical — assume bugs until proven otherwise.
## Repo
Shared checkout at `../shared/repo/`. Force-sync to remote:
`cd ../shared/repo && git fetch origin && git checkout -B {branch} origin/{branch}`
## Review Criteria (inherited from Code Reviewer agent)
1. CORRECTNESS: Logic errors, edge cases, error handling
2. SECURITY: Injection, auth, data exposure, input validation
3. PERFORMANCE: Complexity, allocations, I/O patterns
4. MAINTAINABILITY: Naming, structure, separation of concerns
## Severity
[MUST FIX] / [SHOULD FIX] / [NIT] / [PRAISE]
## Workflow
1. Receive branch + PR # + acceptance criteria from PM
2. Checkout branch, read changes: `git diff main...HEAD`
3. Review code against criteria above
4. Run FULL test suite (not just changed files)
5. Identify test gaps — report to PM, don't commit code yourself
6. Submit PR review via GitHub MCP or gh CLI (APPROVE or REQUEST_CHANGES with line comments)
7. Report to PM: PASS or FAIL with details
## Workflows
- workflow_run code-review: for comprehensive parallel review (correctness + security + style)
- workflow_run test-generation: when reporting test gaps, generate specific suggestions
## Principles
- Don't trust the implementation. That's why you exist.
- Test what's NOT tested, not just what is.
- Focus on behavior, not style.
- Run the FULL test suite. Check for regressions.
"""
[agents.qa.capabilities]
memory_read = ["*"]
memory_write = ["self.*", "shared.*"]
# QA has NO file_write — can't modify code, only verify
shell = [
"cargo test *",
"cargo clippy *",
"cargo audit *",
"npm test *",
"npm run lint *",
"pytest *",
"ruff *",
"go test *",
"golangci-lint *",
"swift test *",
"git *",
"gh *",
]
[agents.qa.resources]
max_llm_tokens_per_hour = 150000
# ─── Dashboard ───────────────────────────────────────────────────────────────
[dashboard]
[[dashboard.metrics]]
label = "Issues Triaged"
memory_key = "devteam_issues_triaged"
format = "number"
[[dashboard.metrics]]
label = "Tasks Completed"
memory_key = "devteam_tasks_completed"
format = "number"
[[dashboard.metrics]]
label = "Active Tasks"
memory_key = "devteam_active_tasks"
format = "number"
[[dashboard.metrics]]
label = "QA Pass Rate"
memory_key = "devteam_qa_pass_rate"
format = "percentage"
# ─── Metadata ────────────────────────────────────────────────────────────────
[metadata]
frequency = "continuous"
token_consumption = "medium"
default_active = false
# ─── i18n ────────────────────────────────────────────────────────────────────
[i18n.zh]
name = "开发团队"
description = "自主软件开发团队 — PM 分拣 Issue，工程师实现，QA 验证"
category = "开发"
[i18n.zh.agents.pm]
name = "产品经理"
description = "产品经理 — 分拣 Issue、分配任务、跟踪进度"
[i18n.zh.agents.engineer]
name = "全栈工程师"
description = "全栈工程师 — 设计、实现、测试"
[i18n.zh.agents.qa]
name = "测试工程师"
description = "QA 工程师 — 验证实现、捕获 Bug"
[i18n.ja]
name = "開発チーム"
description = "自律型開発チーム — PMがIssueをトリアージ、エンジニアが実装、QAが検証"
category = "開発"
[i18n.ko]
name = "개발팀"
description = "자율 개발팀 — PM이 이슈 분류, 엔지니어가 구현, QA가 검증"
category = "개발"
hands/devteam/README.md
+46
View File
@@ -0,0 +1,46 @@
# Dev Team Hand
Autonomous software development team — PM triages issues, Engineer implements, QA validates.
## Composition
This hand demonstrates proper resource composition:
| Resource | How Used |
|----------|----------|
| **Agent templates** | `base = "planner"` / `"coder"` / `"code-reviewer"` — inherit proven prompts |
| **MCP servers** | `github` — agents interact via MCP tools, not hardcoded curl |
| **Workflows** | `bug-triage`, `code-review`, `test-generation`, `product-spec`, etc. — via `workflow_run` tool |
| **Plugins** | `todo-tracker`, `auto-summarizer`, `episodic-memory` |
| **Per-agent skills** | `SKILL-pm.md`, `SKILL-engineer.md`, `SKILL-qa.md` — targeted reference knowledge |
| **Per-agent capabilities** | QA can't write files, Engineer has full shell, PM only uses gh/git |
## Architecture
```
PM (coordinator, base=planner)
├─ Scans GitHub issues via MCP
├─ Triages, delegates, tracks board
├─ Uses workflow_run for bug-triage, product-spec
├─ Merges PRs after QA passes
│
├──▶ Engineer (base=coder)
│ ├─ Clones shared repo, branches, implements
│ ├─ Uses workflow_run for test-generation, refactor-plan
│ ├─ Creates PRs via GitHub MCP
│ └─ Accumulates knowledge per module
│
└──▶ QA (base=code-reviewer)
├─ Reviews code (correctness + security + performance)
├─ Runs full test suite (no file_write access)
├─ Uses workflow_run for comprehensive code-review
└─ Submits PR reviews with line comments
```
## Usage
```bash
librefang hand activate devteam
librefang hand set devteam repo_url "owner/repo"
librefang hand chat devteam
```
hands/devteam/SKILL-engineer.md
+55
View File
@@ -0,0 +1,55 @@
---
name: devteam-engineer-skill
version: "1.0.0"
description: "Engineer reference knowledge — tech stack detection, build commands, git workflow, debugging patterns"
runtime: prompt_only
---
# Engineer Reference Knowledge
## Tech Stack Detection
| File | Stack | Build | Test | Lint |
|------|-------|-------|------|------|
| `Cargo.toml` | Rust | `cargo build` | `cargo test` | `cargo clippy -- -D warnings` |
| `package.json` + `tsconfig.json` | TypeScript | `npm run build` | `npm test` | `npm run lint` |
| `package.json` | JavaScript | `npm run build` | `npm test` | `npm run lint` |
| `go.mod` | Go | `go build ./...` | `go test ./...` | `golangci-lint run` |
| `pyproject.toml` | Python | — | `pytest` | `ruff check .` |
| `pom.xml` | Java | `mvn compile` | `mvn test` | `mvn checkstyle:check` |
| `Package.swift` | Swift | `swift build` | `swift test` | `swiftlint` |
## Git Workflow
```bash
# New task
git checkout main && git pull
git checkout -B feat/issue-42
# Commit (specific files only)
git add path/to/file.rs path/to/test.rs
git commit -m "fix: description (#42)"
git push -u origin feat/issue-42
# Create PR
gh pr create --title "fix: description (#42)" --body "Closes #42" --head feat/issue-42 --base main
# Rebase on conflict
git fetch origin && git rebase origin/main && git push --force-with-lease
```
## Debugging Methodology
1. **REPRODUCE** — get error message, stack trace, exact failure
2. **ISOLATE** — read source, git log/diff, narrow search space
3. **IDENTIFY** — trace data flow, check boundaries, find root cause (not symptoms)
4. **FIX** — minimal correct fix, don't refactor
5. **VERIFY** — write regression test, run full suite
## Common Bug Patterns
- Off-by-one errors, null/None handling
- Resource leaks (file handles, connections)
- Error handling paths (what happens on failure?)
- Race conditions, shared mutable state
- Type mismatches, silent truncation
hands/devteam/SKILL-pm.md
+70
View File
@@ -0,0 +1,70 @@
---
name: devteam-pm-skill
version: "1.0.0"
description: "PM reference knowledge — issue triage framework, GitHub CLI, project board patterns"
runtime: prompt_only
---
# PM Reference Knowledge
## Issue Triage
| Signal | Type |
|--------|------|
| "doesn't work", "error", "crash" | bug |
| "add", "new", "support" | feature |
| "clean up", "simplify", "rename" | refactor |
| "document", "readme" | docs |
| Priority | Criteria |
|----------|----------|
| P0 | Production down, data loss, security |
| P1 | Core feature broken |
| P2 | Feature request, non-critical bug |
| P3 | Nice-to-have, cosmetic |
| Size | Scope |
|------|-------|
| S | < 50 lines, 1 file |
| M | 50-200 lines, 2-5 files |
| L | 200-1000 lines, needs design |
| XL | 1000+, decompose first |
## gh CLI Quick Reference
```bash
# Issues
gh issue list --repo OWNER/REPO --state open --json number,title,labels,assignees --limit 30
gh issue view NUMBER --repo OWNER/REPO --json body,comments
gh issue comment NUMBER --repo OWNER/REPO --body "message"
gh issue close NUMBER --repo OWNER/REPO --reason completed
gh issue edit NUMBER --repo OWNER/REPO --add-label "bot:triaged"
# PRs
gh pr list --repo OWNER/REPO --state open --json number,title,headRefName,statusCheckRollup
gh pr checks NUMBER --repo OWNER/REPO
gh pr merge NUMBER --repo OWNER/REPO --squash
gh pr revert NUMBER --repo OWNER/REPO
# Code browsing
gh api repos/OWNER/REPO/contents/PATH --jq '.content' | base64 -d
```
## Board Schema
```json
{
"backlog": [{"issue": 42, "title": "...", "type": "bug", "size": "M", "priority": "P1"}],
"in_progress": [{"issue": 43, "assignee": "engineer", "branch": "fix/issue-43", "round": 0}],
"in_review": [{"issue": 44, "pr": 50}],
"done": [{"issue": 45, "closed_at": "2025-01-02"}]
}
```
## Scan Interval Mapping
| Setting | schedule_create every_secs |
|---------|--------------------------|
| 5min | 300 |
| 15min | 900 |
| 1hour | 3600 |
hands/devteam/SKILL-qa.md
+75
View File
@@ -0,0 +1,75 @@
---
name: devteam-qa-skill
version: "1.0.0"
description: "QA reference knowledge — review checklist, security audit patterns, test philosophy"
runtime: prompt_only
---
# QA Reference Knowledge
## Code Review Checklist
### Correctness
- Logic errors, off-by-one, unhandled edge cases
- Error handling: all error paths tested?
- Null/undefined safety
- Resource leaks (memory, file handles, connections)
- Concurrency: race conditions, deadlocks, TOCTOU
### Security (OWASP Top 10)
- Injection (SQL, command, XSS, SSTI)
- Authentication/authorization flaws
- Sensitive data exposure (logging secrets, hardcoded keys)
- Input validation gaps
- Insecure cryptographic usage
- Path traversal, SSRF
- Deserialization attacks
### Performance
- Algorithmic complexity (O(n²) loops, unbounded recursion)
- Unnecessary allocations, copies
- N+1 queries, missing caching
- I/O patterns (blocking in async, unbuffered reads)
## Review Format
```
## Summary
[approve / request changes / needs discussion]
## Findings
### [MUST FIX] file.rs:42 — Off-by-one in loop bound
...
### [SHOULD FIX] handler.rs:88 — Missing input validation
...
### [NIT] utils.rs:12 — Consider renaming for clarity
...
### [PRAISE] auth.rs:55 — Clean error handling pattern
...
```
## Testing Philosophy
- Tests document behavior, not implementation
- Test the interface, not the internals
- Every test should fail for exactly one reason
- Prefer fast, deterministic tests
- Test name pattern: `test_{function}_{scenario}_{expected}`
- Arrange → Act → Assert
## gh CLI for Reviews
```bash
# Approve
gh pr review NUMBER --repo OWNER/REPO --approve --body "QA passed"
# Request changes
gh pr review NUMBER --repo OWNER/REPO --request-changes --body "Found issues, see comments"
# Add line comment (via API, gh CLI doesn't support line comments directly)
gh api repos/OWNER/REPO/pulls/NUMBER/reviews \
--method POST \
-f event=REQUEST_CHANGES \
-f body="See line comments" \
--input - <<< '{"comments":[{"path":"src/file.rs","line":42,"body":"Off-by-one here"}]}'
```