ai-playbook 1.0.0

package/README.md

@@ -0,0 +1,146 @@
+# AI Playbook
+
+AI Playbook is a structured knowledge base for AI-supported roles, skills,
+workflows, prompts, tool integrations, and project context.
+
+This repository is not an application runtime. It is an operating manual that a
+human or AI agent can load selectively to understand how to perform a task in a
+specific role, domain, project, or tool environment.
+
+## Repository Contract
+
+The playbook is organized around four core concepts:
+
+| Concept | Meaning |
+| --- | --- |
+| Role | How an agent should operate: responsibilities, workflow, decision posture, communication style, and quality gates. |
+| Skill | What an agent can do: reusable domain capability, execution guidance, examples, checklists, workflows, and templates. |
+| Context | What an agent must know: company, engineering, architecture, communication, project, and domain background. |
+| Tooling | What an agent can use: MCP connectors, commands, hooks, model notes, and automation patterns. |
+
+Roles route work. Skills provide capability. Context shapes decisions. Tooling
+connects the playbook to real systems.
+
+## Folder Meanings
+
+| Folder | Meaning | Typical Contents |
+| --- | --- | --- |
+| `adr/` | Architecture decision records. | Decision logs, trade-off records, accepted/rejected alternatives. |
+| `agents/` | Agent persona or worker definitions. | Architect, coder, reviewer, tester, planner, researcher, and specialist agents. |
+| `checklists/` | Shared quality gates that are not tied to a single role or skill. | Release checks, review checks, task completion checks. |
+| `commands/` | Reusable command recipes or command-style workflows. | Local development commands, validation commands, task commands. |
+| `context/` | Shared context that affects decisions. | Engineering culture, architecture, communication rules, company context, domain context. |
+| `docs/` | Design notes, plans, reports, generated work packages, and long-form documentation. | Specs, implementation plans, reviews, reports. |
+| `examples/` | Cross-cutting examples that do not belong to one skill packet. | Conversations, prompts, pull requests, runbooks, case studies. |
+| `hooks/` | Hook definitions and automation trigger guidance. | Pre-task, post-task, pre-commit, review, deployment, test-before-finish hooks. |
+| `knowledge/` | Durable reference knowledge that is broader than one role or project. | Research notes, domain explanations, reusable reference material. |
+| `mcp/` | MCP connector and external tool integration notes. | GitHub, filesystem, browser, database, Jira, Slack, Notion, Playwright connector docs. |
+| `models/` | Model-specific guidance. | Codex, Claude, Gemini, OpenAI, Cursor, Aider, Continue, Warp notes. |
+| `patterns/` | Reusable solution patterns. | Architecture patterns, prompt patterns, code patterns, review patterns. |
+| `personas/` | Communication or collaboration personas. | Stakeholder styles, reviewer styles, domain expert personas. |
+| `projects/` | Project-specific context and constraints. | Product goals, domain constraints, architecture notes, compliance requirements. |
+| `prompts/` | Prompt assets grouped by task or role. | Developer prompts, reviewer prompts, architect prompts, support prompts. |
+| `roles/` | Role operating models. | `role.md`, `workflow.md`, `skill-map.md`, `triggers.md`, `checklists.md`, examples. |
+| `shared/` | Shared fragments used by multiple packets. | Common language, shared policies, reusable snippets. |
+| `skills/` | Reusable capability packets. | `skill.md`, `README.md`, examples, checklists, workflows, templates. |
+| `snippets/` | Small reusable text or code fragments. | PR text, review comments, prompt snippets, doc fragments. |
+| `templates/` | Skeletons for creating consistent repository artifacts. | Role templates, skill templates, ADR templates, project templates. |
+| `workflows/` | Cross-role workflows broader than a single role or skill. | Release flow, incident flow, discovery flow, review flow. |
+
+## Loading Model
+
+AI agents should load content in this order:
+
+1. Load the requested `role`, if one is specified.
+2. Load the role's `skill-map.md` or explicit skill references.
+3. Load only the relevant `skills/<skill>/` files needed for the task.
+4. Load global context from `context/`.
+5. Load project context from `projects/<project>/` when the task involves a specific project.
+6. Load MCP, model, command, or hook notes only when the task requires that integration.
+
+The goal is selective loading: enough context to act correctly, not every file in
+the repository.
+
+## Standard Skill Packet
+
+Each skill should use this structure unless there is a strong reason not to:
+
+```text
+skills/<skill-name>/
++-- README.md
++-- skill.md
++-- examples.md
++-- checklists.md
++-- workflows.md
++-- templates/
+```
+
+| File | Purpose |
+| --- | --- |
+| `README.md` | Human-readable overview and routing guidance. |
+| `skill.md` | Core instructions for how an agent applies the skill. |
+| `examples.md` | Concrete examples of good outputs or workflows. |
+| `checklists.md` | Quality gates and completion checks. |
+| `workflows.md` | Repeatable execution flows. |
+| `templates/` | Reusable prompts, documents, or artifact skeletons. |
+
+Minimal skill packets may start with only `README.md`, `skill.md`, and
+`examples.md`, but active references should not point to missing files.
+
+## Standard Role Packet
+
+Each role should use this structure:
+
+```text
+roles/<role-name>/
++-- README.md
++-- role.md
++-- responsibilities.md
++-- workflow.md
++-- triggers.md
++-- skill-map.md
++-- checklists.md
++-- examples.md
+```
+
+| File | Purpose |
+| --- | --- |
+| `README.md` | Role overview and navigation. |
+| `role.md` | Core role definition, posture, and decision principles. |
+| `responsibilities.md` | Duties, boundaries, and ownership. |
+| `workflow.md` | Step-by-step operating flow. |
+| `triggers.md` | Events that activate the role or workflow. |
+| `skill-map.md` | Mapping from task types to required skills and context. |
+| `checklists.md` | Role-level quality gates. |
+| `examples.md` | Example interactions, outputs, or decisions. |
+
+Roles explain how an agent should behave. Skills explain what capability the
+agent can apply.
+
+## Placement Rules
+
+- Put reusable capability guidance in `skills/`.
+- Put role behavior, responsibility, and workflow guidance in `roles/`.
+- Put project facts and constraints in `projects/`.
+- Put cross-project facts in `context/`.
+- Put tool-specific setup or connector behavior in `mcp/`, `commands/`, or `models/`.
+- Put reusable skeletons in `templates/`.
+- Put generated plans, specs, reports, and review packages in `docs/`.
+- Do not link to a planned file as if it already exists.
+
+## Authoring Rules
+
+- Keep paths stable and repository-relative.
+- Use lowercase kebab-case for new directories and files.
+- Prefer `checklists.md`, `examples.md`, `workflows.md`, and `templates/` for collections.
+- Prefer `skill.md` and `role.md` for core definitions.
+- Keep each file actionable: tell the agent what to load, decide, do, verify, or produce.
+- Separate durable guidance from one-off generated work.
+
+## Current Reshape Priorities
+
+1. Normalize references so every role points at real skill paths.
+2. Fill empty root and context docs with concise contracts.
+3. Keep skill packets consistent across domains.
+4. Separate reusable skill guidance from project/service boilerplate.
+5. Add templates before adding large volumes of new content.

package/agents/README.md

@@ -0,0 +1,168 @@
+# AI Agents
+
+Specialized agents for different roles and responsibilities in software engineering and product development.
+
+## Overview
+
+Agents are specialized AI assistants configured for specific domains and responsibilities. Each agent has:
+
+- **Focused expertise** in their domain
+- **Curated tool access** appropriate for their role
+- **Clear responsibilities** and use cases
+- **Consistent output formats** for their domain
+
+## Available Agents
+
+### Core Development
+
+| Agent | Purpose | Best For |
+|-------|---------|----------|
+| **[architect](./architect/AGENT.md)** | Systems and solution architecture | Designing architectures, data flows, scaling strategies |
+| **[coder](./coder/AGENT.md)** | Production code implementation | Implementing features, writing production code |
+| **[debugger](./debugger/AGENT.md)** | Issue diagnosis and debugging | Root cause analysis, bug fixes, error investigation |
+| **[tester](./tester/AGENT.md)** | Testing and quality assurance | Writing tests, test strategies, validation |
+| **[refactorer](./refactorer/AGENT.md)** | Code quality improvement | Refactoring, removing duplication, modernizing |
+
+### Quality and Review
+
+| Agent | Purpose | Best For |
+|-------|---------|----------|
+| **[reviewer](./reviewer/AGENT.md)** | Code quality assessment | Code reviews, quality checks, standards adherence |
+| **[security](./security/AGENT.md)** | Security analysis | Vulnerability identification, threat modeling, compliance |
+| **[performance](./performance/AGENT.md)** | Performance optimization | Bottleneck identification, optimization, profiling |
+
+### Planning and Management
+
+| Agent | Purpose | Best For |
+|-------|---------|----------|
+| **[planner](./planner/AGENT.md)** | Project and feature planning | Breaking down work, estimates, roadmaps |
+| **[product-owner](./product-owner/AGENT.md)** | Product requirements | User stories, features, prioritization |
+| **[release-manager](./release-manager/AGENT.md)** | Release coordination | Versioning, deployment, rollback strategies |
+
+### Operations and Support
+
+| Agent | Purpose | Best For |
+|-------|---------|----------|
+| **[devops](./devops/AGENT.md)** | Infrastructure and deployment | CI/CD, IaC, containers, monitoring |
+| **[support](./support/AGENT.md)** | Customer support | Troubleshooting, diagnostics, help documentation |
+
+### Research and Knowledge
+
+| Agent | Purpose | Best For |
+|-------|---------|----------|
+| **[researcher](./researcher/AGENT.md)** | Codebase and technology research | Architecture analysis, pattern identification, exploration |
+| **[documentation](./documentation/AGENT.md)** | Documentation creation | API docs, guides, architecture docs, README |
+
+## Agent Selection Guide
+
+Choose an agent based on your task:
+
+### I need to...
+
+- **Design a system** → Use `architect`
+- **Write code** → Use `coder`
+- **Fix a bug** → Use `debugger`
+- **Write tests** → Use `tester`
+- **Improve code quality** → Use `refactorer`
+- **Review code** → Use `reviewer`
+- **Find security issues** → Use `security`
+- **Optimize performance** → Use `performance`
+- **Plan work** → Use `planner`
+- **Define requirements** → Use `product-owner`
+- **Manage a release** → Use `release-manager`
+- **Set up infrastructure** → Use `devops`
+- **Help customers** → Use `support`
+- **Research a topic** → Use `researcher`
+- **Write documentation** → Use `documentation`
+
+## Using an Agent
+
+### Basic Usage
+
+```
+Use [agent-name] to [task description]
+```
+
+Example:
+```
+Use architect to design the data flow for a real-time notification system
+```
+
+### With Context
+
+```
+Use [agent-name] to [task] because [context/constraints]
+```
+
+Example:
+```
+Use debugger to find why database migrations are failing on prod, we see timeout errors
+```
+
+### With Specifics
+
+```
+Use [agent-name] to [task] in [scope], focusing on [aspect]
+```
+
+Example:
+```
+Use refactorer to consolidate duplicate auth logic across 3 middleware files, focusing on clarity
+```
+
+## Agent Capabilities
+
+Each agent has:
+
+- **Domain expertise** in their specialization
+- **Appropriate tools** for their role (code reading, execution, documentation, research)
+- **Clear success criteria** for their outputs
+- **Integration** with other agents for complex tasks
+
+## Combining Agents
+
+For complex tasks, use multiple agents in sequence:
+
+1. **Plan the work** → Use `planner` to break down requirements
+2. **Design the system** → Use `architect` to design components
+3. **Implement** → Use `coder` to write code
+4. **Review quality** → Use `reviewer` to check code quality
+5. **Test** → Use `tester` to write and run tests
+6. **Secure** → Use `security` to identify vulnerabilities
+7. **Optimize** → Use `performance` to improve efficiency
+8. **Document** → Use `documentation` to create guides
+
+## Agent Tool Access
+
+Each agent has different tools to support their role:
+
+- **Read/Write/Edit**: Code and file modification
+- **Grep/Glob**: Code search and pattern matching
+- **Bash**: System commands and execution
+- **WebFetch/WebSearch**: External research
+- **NotebookEdit**: Jupyter notebook support
+
+See individual agent definitions for specific tool access.
+
+## Best Practices
+
+### When Using Agents
+
+- **Be specific** about the problem or task
+- **Provide context** about constraints and goals
+- **Review outputs** before acting on recommendations
+- **Combine agents** for complex multi-step tasks
+- **Save results** for future reference
+
+### Choosing Between Agents
+
+- `architect` designs systems, `coder` implements them
+- `reviewer` assesses quality, `refactorer` improves code
+- `tester` validates, `debugger` diagnoses failures
+- `planner` breaks down work, `product-owner` defines requirements
+
+## Version
+
+**Version:** 1.0
+
+Agent definitions are foundational and stable. Updates reflect new capabilities or role definitions.