{
  "markdown": "# Flowbaby Agent Team\n\n> A multi-agent workflow system for GitHub Copilot in VS Code that brings structure, quality gates, and long-term memory to AI-assisted development.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## What This Is\n\nThe Flowbaby Agent Team is the **reference implementation** for Flowbaby’s persistent memory system.\n\nThese agents are intentionally designed to take advantage of long-term, workspace-scoped memory. They demonstrate what agent workflows look like when memory is treated as infrastructure rather than chat history.\n\n## The Problem\n\nAI coding assistants are powerful but chaotic:\n- They forget context between sessions\n- They try to do everything at once (plan, code, test, review)\n- They skip quality gates and security reviews\n- They lose track of decisions made earlier\n\n## The Solution\n\nThis repository provides **specialized AI agents** that each own a specific part of your development workflow:\n\n| Agent | Role |\n|-------|------|\n| **Roadmap** | Product vision and epics |\n| **Planner** | Implementation-ready plans (WHAT, not HOW) |\n| **Analyst** | Deep technical research |\n| **Architect** | System design and patterns |\n| **Critic** | Plan quality review |\n| **Security** | Comprehensive security assessment |\n| **Implementer** | Code and tests |\n| **Code Reviewer** | Code quality gate before QA |\n| **QA** | Test strategy and verification |\n| **UAT** | Business value validation |\n| **DevOps** | Packaging and releases |\n| **Retrospective** | Lessons learned |\n| **ProcessImprovement** | Workflow evolution |\n\nEach agent has **clear constraints** (Planner can't write code, Implementer can't redesign) and produces **structured documents** that create an audit trail.\n\nUse as many or as few as you need, in any order. They are designed to know their own role and work together with other agents in this repo. They are designed to work together to create a structured and auditable development process. They are also designed to challenge each other to ensure the best possible outcome.\n\n## Quick Start\n\n### 1. Get the Agents\n\n```bash\ngit clone https://github.com/groupzer0/agents.git\n```\n\n### 2. Add to Your Project\n\nCopy agents to your workspace (per-repo, recommended):\n```text\nyour-project/\n└── .github/\n    └── agents/\n        ├── planner.agent.md\n        ├── implementer.agent.md\n        └── ... (others you need)\n```\n\nOr install them at the **user level** so they are available across all VS Code workspaces. User-level agents are stored in your [VS Code profile folder](https://code.visualstudio.com/docs/configure/profiles):\n\n- **Linux**: `~/.config/Code/User/`\n- **macOS**: `~/Library/Application Support/Code/User/`\n- **Windows**: `%APPDATA%\\Code\\User\\`\n\n> [!TIP]\n> The easiest way to create a user-level agent is via the Command Palette: **Chat: New Custom Agent** → select **User profile**. VS Code will place it in the correct location automatically.\n\n\n### 3. Use in Copilot Chat\n\nIn VS Code, select your agent from the **agents dropdown** at the top of the Chat panel, then type your prompt:\n\n```text\nCreate a plan for adding user authentication\n```\n\n> [!NOTE]\n> Unlike built-in participants (e.g., `@workspace`), custom agents are **not** invoked with the `@` symbol. You must select them from the dropdown or use the Command Palette.\n\n### 4. Flowbaby Requirement\n\nThese agents require Flowbaby to function correctly.\n\nFlowbaby provides the persistent memory layer that allows agents to remember decisions, constraints, and prior work across sessions. Without Flowbaby, the agents fall back to stateless behavior and lose most of their intended value.\n\nInstall [Flowbaby](https://marketplace.visualstudio.com/items?itemName=flowbaby.flowbaby) for cross-session memory:\n\n1. VS Code Extensions → Search \"Flowbaby\" → Install\n2. Command Palette → \"Flowbaby: Initialize Workspace\"\n3. Command Palette → \"Flowbaby: Set API Key\"\n\nFlowbaby governs memory usage and evaluation limits for these agents.\n\n### 5. (Optional) Use with GitHub Copilot CLI\n\nYou can also use these agents with the GitHub Copilot CLI by placing your `.agent.md` files under `.github/agents/` in each repository where you run the CLI, then invoking them with commands like:\n\n```bash\ncopilot --agent planner --prompt \"Create a plan for adding user authentication\"\n```\n\n**Known limitation (user-level agents):** The Copilot CLI currently has an upstream bug where user-level agents in `~/.copilot/agents/` are not loaded, even though they are documented ([github/copilot-cli#452](https://github.com/github/copilot-cli/issues/452)). This behavior and the recommended per-repository workaround were identified and documented by @rjmurillo. Until the bug is fixed, prefer `.github/agents/` in each repo.\n\n\n## Documentation\n\n| Document | Purpose |\n|----------|---------|\n| [USING-AGENTS.md](USING-AGENTS.md) | Quick start guide (5 min read) |\n| [AGENTS-DEEP-DIVE.md](AGENTS-DEEP-DIVE.md) | Comprehensive documentation |\n| [CHANGELOG.md](CHANGELOG.md) | Notable repository changes |\n| [memory-contract-example.md](vs-code-agents/memory-contract-example.md) | Memory usage patterns |\n\n---\n\n### Typical Workflow\n\n```text\nRoadmap → Planner → Analyst/Architect/Security/Critic → Implementer → Code Reviewer → QA → UAT → DevOps\n```\n\n1. **Roadmap** defines what to build and why\n2. **Planner** creates a structured plan at the feature level or smaller\n3. **Analyst** researches unknowns\n4. **Architect** ensures design fit. Enforces best practices.\n5. **Security** audits for vulnerabilities. Recommends best practices.\n6. **Critic** reviews plan quality\n7. **Implementer** writes code\n8. **Code Reviewer** verifies code quality\n9. **QA** verifies tests. Ensures robust test coverage\n10. **UAT** confirms business value was delivered\n11. **DevOps** releases (with user approval)\n\n---\n\n## Key Features\n\n### 🎯 Separation of Concerns\nEach agent has one job. Planner plans. Implementer implements. No scope creep.\n\n### 📝 Document-Driven\nAgents produce Markdown documents in `agent-output/`. Every decision is recorded.\n\n### 🔒 Quality Gates\nCritic reviews plans. Security audits code. QA verifies tests. Nothing ships without checks.\n\n### 🧠 Robust Memory\nWith [Flowbaby](https://github.com/groupzer0/flowbaby), agents remember decisions across sessions.\n\n### 🔄 Handoffs\nAgents hand off to each other with context. No lost information between phases.\n\n---\n\n## Flowbaby Memory Integration\n\n[Flowbaby](https://github.com/groupzer0/flowbaby) is a VS Code extension that solves a specific problem: Copilot forgets what you've discussed. Across sessions, developers repeatedly re-explain context, architecture decisions, and constraints. Flowbaby captures, summarizes, and resurfaces relevant prior work automatically—bridging context between sessions and maintaining continuity within long-running conversations.\n\nThe persistent memory layer that powers the Flowbaby Agent Team.\n\n### Links\n\n- **GitHub**: https://github.com/groupzer0/flowbaby\n- **VS Code Marketplace**: https://marketplace.visualstudio.com/items?itemName=flowbaby.flowbaby\n- **Documentation**: See the GitHub README for full setup guide\n\n---\n\n## Repository Structure\n\n```text\nagents/\n├── CHANGELOG.md                 # Notable changes\n├── README.md                    # This file\n├── USING-AGENTS.md              # Quick start guide\n├── AGENTS-DEEP-DIVE.md          # Comprehensive documentation\n├── LICENSE                      # MIT License\n└── vs-code-agents/              # Agent definitions\n    ├── analyst.agent.md\n    ├── architect.agent.md\n    ├── critic.agent.md\n    ├── devops.agent.md\n    ├── implementer.agent.md\n    ├── pi.agent.md              # ProcessImprovement\n    ├── planner.agent.md\n    ├── qa.agent.md\n    ├── code-reviewer.agent.md\n    ├── retrospective.agent.md\n    ├── roadmap.agent.md\n    ├── security.agent.md\n    ├── uat.agent.md\n    └── reference/\n        └── memory-contract-example.md\n```\n\n---\n\n## Security Agent Highlight\n\nThe **Security Agent** has been enhanced to provide truly comprehensive security reviews:\n\n### Five-Phase Framework\n1. **Architectural Security**: Trust boundaries, STRIDE threat modeling, attack surface mapping\n2. **Code Security**: OWASP Top 10, language-specific vulnerability patterns\n3. **Dependency Security**: CVE scanning, supply chain risk assessment\n4. **Infrastructure Security**: Headers, TLS, container security\n5. **Compliance**: OWASP ASVS, NIST, industry standards\n\n### Why This Matters\n\nMost developers don't know how to conduct thorough security reviews. They miss:\n- Architectural weaknesses (implicit trust, flat networks)\n- Language-specific vulnerabilities (prototype pollution, pickle deserialization)\n- Supply chain risks (abandoned packages, dependency confusion)\n- Compliance gaps (missing security headers, weak TLS)\n\nThe Security Agent systematically checks all of these, producing actionable findings with severity ratings and remediation guidance.You can then hand this off to the Planner agent and the Implementer to address. \n\nSee [security.agent.md](vs-code-agents/security.agent.md) for the full specification.\n\n---\n\n## Customization\n\n### Modify Existing Agents\n\nEdit `.agent.md` files to adjust:\n- `description`: What shows in Copilot\n- `tools`: Which VS Code tools the agent can use\n- `handoffs`: Other agents it can hand off to\n- Responsibilities and constraints\n\n### Create New Agents\n\n1. Create `your-agent.agent.md` following the existing format\n2. Define purpose, responsibilities, constraints\n3. Include the Memory Contract section\n4. Add to `.github/agents/` in your workspace\n\n---\n\n## Recent Updates\n\nRecent commits introduced significant improvements to agent workflow and capabilities:\n\n### Uncertainty-Aware Issue Analysis (2026-01-15)\n\nAgents now explicitly avoid forced root-cause narratives when evidence is missing.\n\n- **Analyst**: Uses an objective hard pivot trigger (timebox/evidence gate) to switch from RCA attempts to system hardening + telemetry requirements.\n- **Architect**: Treats insufficient observability as an architectural risk; defines normal vs debug logging guidance and a minimum viable incident telemetry baseline.\n- **QA**: Validates diagnosability improvements; prefers asserting structured telemetry fields/events over brittle log string matching.\n- **Template**: `vs-code-agents/reference/uncertainty-review-template.md` provides a repeatable output format.\n\n### Skills System (2025-12-19)\n\nAgents now use **Claude Skills**—modular, reusable instruction sets that load on-demand:\n\n| Skill | Purpose |\n|-------|---------|\n| `memory-contract` | Unified Flowbaby memory retrieval/storage contract |\n| `analysis-methodology` | Confidence levels, gap tracking, investigation techniques |\n| `architecture-patterns` | ADR templates, patterns, anti-pattern detection |\n| `code-review-checklist` | Pre/post-implementation review criteria |\n| `code-review-standards` | Code review checklist, severity definitions, document templates |\n| `cross-repo-contract` | Multi-repo API type safety and contract coordination |\n| `document-lifecycle` | Unified numbering, automated closure, orphan detection |\n| `engineering-standards` | SOLID, DRY, YAGNI, KISS with detection patterns |\n| `release-procedures` | Two-stage release workflow, semver, platform constraints |\n| `security-patterns` | OWASP Top 10, language-specific vulnerabilities |\n| `testing-patterns` | TDD workflow, test pyramid, coverage strategies |\n\n**Skill Placement:**\n- **VS Code Stable (1.107.1)**: Place in `.claude/skills/`\n- **VS Code Insiders**: Place in `.github/skills/`\n\n> [!NOTE]\n> These locations are changing with upcoming VS Code releases. The `.github/skills/` location is becoming the standard. See the [VS Code Agent Skills documentation](https://code.visualstudio.com/docs/copilot/customization/agent-skills) for the latest guidance.\n\n### Key Agent Flow Improvements\n\n- **TDD mandatory**: Implementer and QA now require Test-Driven Development for new feature code\n- **Two-stage release**: DevOps commits locally first; pushes only on explicit release approval\n- **Document status tracking**: All agents update Status fields in planning docs (\"Draft\", \"In Progress\", \"Released\")\n- **Open Question Gate**: Implementer halts if plans have unresolved questions; requires explicit user acknowledgment to proceed\n- **Memory as skill**: Memory contract moved from inline in each agent to a loadable `memory-contract` skill\n- **Slimmed Security agent**: Reduced by 46% using skill references instead of inline content\n\n### Cross-Repository Contract Skill (2025-12-26)\n\nNew `cross-repo-contract` skill for projects with runtime + backend repos that need to stay aligned:\n\n- **Contract discovery**: Agents check `api-contract/` or `.contracts/` for type definitions\n- **Type safety enforcement**: Implementer verifies contract definitions before coding API endpoints/clients\n- **Breaking change coordination**: Plans must document contract changes and sync dependencies\n- **Quality gate**: Critic verifies multi-repo plans address contract adherence\n\nIntegrated into Architect, Planner, Implementer, and Critic agents.\n\n### Document Lifecycle System (2025-12-24)\n\nNew `document-lifecycle` skill implementing:\n\n- **Unified numbering**: All documents in a work chain share the same ID (analysis 080 → plan 080 → qa 080 → uat 080)\n- **Automated closure**: Documents move to `closed/` subfolders after commit\n- **Orphan detection**: Agents self-check + Roadmap periodic sweep\n\nThis keeps active plans visible while archiving completed work for traceability.\n\n### Previous Updates\n\n- **Refined Flowbaby memory contract (2025-12-16)**: All core agents share a unified memory contract. Agents function without Flowbaby but greatly benefit from its use.\n- **Aligned agent tool names with VS Code APIs (2025-12-16)**: Agent `tools` definitions now use official VS Code agent tool identifiers.\n- **Added subagent usage patterns (2025-12-15)**: Planner, Implementer, QA, Analyst, and Security document how to invoke each other as scoped subagents.\n- **Background Implementer mode (2025-12-15)**: Implementation can run as local chat or background agent in isolated Git worktree.\n\n## Contributing\n\nContributions welcome! Areas of interest:\n\n- **Agent refinements**: Better constraints, clearer responsibilities\n- **New agents**: For specialized workflows (e.g., Documentation, Performance)\n- **Memory patterns**: Better retrieval/storage strategies\n- **Documentation**: Examples, tutorials, troubleshooting\n\nThis repository also runs an automatic **Markdown lint** check in GitHub Actions on pushes and pull requests that touch `.md` files. The workflow uses `markdownlint-cli2` with a shared configuration, and helps catch issues like missing fenced code block languages (MD040) early in review. This lint workflow was proposed based on feedback and review from @rjmurillo.\n\n---\n\n## Requirements\n\n- VS Code with GitHub Copilot\n- For memory: [Flowbaby extension](https://marketplace.visualstudio.com/items?itemName=flowbaby.flowbaby) + Python 3.10+\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE)\n\n---\n\n## Related Resources\n\n- [GitHub Copilot Agents Documentation](https://code.visualstudio.com/docs/copilot/copilot-agents)\n- [Flowbaby Extension](https://github.com/groupzer0/flowbaby)\n- [OWASP Top 10](https://owasp.org/www-project-top-ten/)\n- [OWASP ASVS](https://owasp.org/www-project-application-security-verification-standard/)\n",
  "bytes": 15452,
  "sha": "eb4da715244f90d6c6013fc976ebd04d38b91c4b1a02968ab53678ab34ad38e5",
  "repo_slug": "groupzer0/vs-code-agents",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_groupzer0_vs_code_agents_vs_code_agents__80812cc9/readme"
}