diff --git a/hands/README.md b/hands/README.md index 6ca99e0..d69db98 100644 --- a/hands/README.md +++ b/hands/README.md @@ -1,94 +1,130 @@ # 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 ``` 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/ -│ ├── HAND.toml # Hand definition -│ └── SKILL.md # Expert knowledge for the agent -├── trader/ │ ├── 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 ```toml -id = "hand-id" # Must match directory name +id = "hand-id" name = "Hand Name" description = "What this hand does" -category = "productivity" # communication | content | data | development | - # devops | finance | productivity | research | social +category = "development" 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] aliases = ["activate phrases"] weak_aliases = ["keyword hints"] -[[requires]] # External dependencies -key = "python3" -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 ─────────────────────────────────────────────── +[dashboard] [[dashboard.metrics]] -label = "Tasks Completed" +label = "Tasks Done" memory_key = "metric_key" format = "number" + +# ─── i18n ──────────────────────────────────────────────────── +[i18n.zh] +name = "中文名" +description = "中文描述" ``` -## Current Hands (14) +## Current Hands (15) -| Hand | Category | Description | -|------|----------|-------------| -| analytics | data | Data analytics, visualization, dashboards, and automated reporting | -| apitester | development | API testing, endpoint discovery, load testing, and regression detection | -| browser | productivity | Web navigation, form filling, and multi-step web tasks | -| clip | content | Turns long-form video into short clips with captions and thumbnails | -| collector | data | Intelligence collection, change detection, and knowledge graphs | -| devops | development | CI/CD management, infrastructure monitoring, and incident response | -| lead | data | Lead generation, enrichment, scoring, and scheduled delivery | -| linkedin | communication | LinkedIn content creation, networking, and engagement | -| predictor | data | Signal collection, calibrated predictions, and accuracy tracking | -| reddit | communication | Subreddit monitoring, content posting, and engagement tracking | -| researcher | productivity | Deep research, cross-referencing, fact-checking, and reports | -| strategist | productivity | Market research, competitive analysis, and strategic planning | -| trader | data | Market intelligence, multi-signal analysis, and risk management | -| twitter | communication | Twitter/X content creation, scheduling, and performance tracking | +| Hand | Category | Agents | Description | +|------|----------|--------|-------------| +| analytics | data | multi | Data analytics, visualization, and automated reporting | +| apitester | development | single | API testing, endpoint discovery, and load testing | +| browser | productivity | single | Web navigation, form filling, and multi-step web tasks | +| clip | content | multi | Long-form video to short clips with captions | +| collector | data | multi | Intelligence collection and change detection | +| **devteam** | **development** | **multi** | **Autonomous dev team — PM + Engineer + QA with base templates** | +| devops | development | multi | CI/CD management, monitoring, and incident response | +| lead | data | multi | Lead generation, enrichment, and scoring | +| linkedin | communication | multi | LinkedIn content creation and networking | +| predictor | data | single | Signal collection and calibrated predictions | +| reddit | communication | multi | Subreddit monitoring and content posting | +| researcher | productivity | multi | Deep research, fact-checking, and reports | +| strategist | productivity | multi | Market research and competitive analysis | +| trader | data | multi | Market intelligence and risk management | +| twitter | communication | multi | Twitter/X content creation and scheduling | ## Adding a New Hand -1. Create `hands//HAND.toml` and `SKILL.md` (expert knowledge for the agent) -2. Ensure `id` matches the directory name -3. Run `python scripts/validate.py` -4. Submit a PR +1. Create `hands//HAND.toml` +2. Add `SKILL.md` (shared) or `SKILL-{role}.md` (per-agent) for reference knowledge +3. Use `base = "agent-name"` to inherit from existing agent templates in `agents/` +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. diff --git a/hands/devteam/HAND.toml b/hands/devteam/HAND.toml new file mode 100644 index 0000000..862003a --- /dev/null +++ b/hands/devteam/HAND.toml @@ -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 = "개발" diff --git a/hands/devteam/README.md b/hands/devteam/README.md new file mode 100644 index 0000000..ce7c11f --- /dev/null +++ b/hands/devteam/README.md @@ -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 +``` diff --git a/hands/devteam/SKILL-engineer.md b/hands/devteam/SKILL-engineer.md new file mode 100644 index 0000000..7a25858 --- /dev/null +++ b/hands/devteam/SKILL-engineer.md @@ -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 diff --git a/hands/devteam/SKILL-pm.md b/hands/devteam/SKILL-pm.md new file mode 100644 index 0000000..0f35e23 --- /dev/null +++ b/hands/devteam/SKILL-pm.md @@ -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 | diff --git a/hands/devteam/SKILL-qa.md b/hands/devteam/SKILL-qa.md new file mode 100644 index 0000000..fe55b95 --- /dev/null +++ b/hands/devteam/SKILL-qa.md @@ -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"}]}' +```