openteam 0.1.0

package/examples/dev-team/skills/architecture-review/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: architecture-review
+description: "Review implemented code for architectural compliance, detect entropy (bloat, duplication, boundary violations), and propose corrections. Use after Developer completes implementation, or periodically to audit codebase health."
+---
+
+# Architecture Review
+
+Review code changes for architectural integrity, detecting and correcting the entropy that naturally accumulates in AI-assisted development.
+
+## Philosophy
+
+> "High internal quality leads to faster delivery of new features, because there is less cruft to get in the way... experienced developers reckon that attention to internal quality pays off in weeks not months." — Martin Fowler
+
+Entropy is the default outcome of development. Every feature adds code, and without active stewardship, the codebase becomes harder to understand, modify, and extend. Your review is the immune system.
+
+> "Knowing your architecture is sacrificial doesn't mean abandoning the internal quality of the software." — Martin Fowler (Sacrificial Architecture)
+
+Even if the entire system will be rewritten someday, internal quality still matters NOW — it determines how fast you can ship features TODAY.
+
+## When to Use
+
+- After Developer completes implementation (before QA verification)
+- When you notice code complexity growing in a module
+- Periodically as a codebase health check
+- When multiple features have been added without review
+
+## Review Checklist
+
+### 1. Plan Compliance
+- [ ] Do the changes match the implementation plan?
+- [ ] Are there unexpected new files or modules? (Why?)
+- [ ] Were any plan items skipped or altered? (Justified?)
+
+### 2. Boundary Integrity
+- [ ] Do modules still have clear, single responsibilities?
+- [ ] Are there any new cross-module dependencies that shouldn't exist?
+- [ ] Is any module reaching into another module's internals instead of using its public API?
+- [ ] Are there any new circular dependencies?
+
+### 3. Duplication Detection
+- [ ] Is any new code duplicating logic that exists elsewhere?
+- [ ] Could any new utility function be merged with an existing one?
+- [ ] Are there copy-paste patterns that should be abstracted?
+
+### 4. Complexity Assessment
+- [ ] Are new functions/classes doing one thing well, or are they multi-purpose?
+- [ ] Are there functions longer than ~50 lines that should be decomposed?
+- [ ] Is the nesting depth reasonable (max 3 levels)?
+- [ ] Are error paths handled, not swallowed?
+
+### 5. Convention Adherence
+- [ ] Do new files follow the project's naming conventions?
+- [ ] Does new code follow the project's error handling patterns?
+- [ ] Is the coding style consistent with the rest of the codebase?
+- [ ] Are new exports intentional (not accidentally public)?
+
+### 6. Bloat Assessment
+- [ ] Can any new file be eliminated by integrating its content into existing files?
+- [ ] Are there over-abstractions (interfaces with a single implementation, classes with a single method)?
+- [ ] Were any "just in case" features or parameters added beyond the requirement?
+
+## Severity Levels
+
+- **Critical** — Boundary violation, circular dependency, data integrity risk → Must fix before QA
+- **Major** — Significant duplication, wrong module placement, convention violation → Should fix before QA
+- **Minor** — Style inconsistency, slightly suboptimal approach, missing comments → Can fix later
+- **Note** — Observation for future consideration, not blocking
+
+## Review Output Format
+
+```markdown
+# Architecture Review: [Feature/PR Title]
+
+**Plan**: [link to implementation plan]
+**Reviewer**: [architect name]
+**Verdict**: ✅ Approved | ⚠️ Approved with notes | 🔴 Changes required
+
+## Summary
+One paragraph overall assessment.
+
+## Findings
+
+### [Critical/Major/Minor] — [Title]
+**Location**: `path/to/file.js:L42`
+**Issue**: [what's wrong]
+**Impact**: [why it matters]
+**Suggestion**: [how to fix]
+
+### ...
+
+## Metrics
+- Files changed: [n]
+- Files added: [n] (justified: [y/n])
+- Lines added: [n]
+- Lines removed: [n]
+- Net complexity change: [simpler / same / more complex]
+
+## Technical Debt
+- [Any new debt introduced, with priority for addressing it]
+```
+
+## Guidelines
+
+- **Be specific.** "The code is messy" is not a review. Point to exact files, lines, and patterns.
+- **Suggest, don't just criticize.** Every issue should come with a proposed fix or direction.
+- **Pick your battles.** Minor style issues shouldn't block a review. Focus on structural integrity.
+- **Acknowledge good work.** If the implementation is clean, say so. Positive feedback reinforces good patterns.
+- **Think in trajectories.** One boundary violation is minor. The pattern of boundary violations is critical. Flag trends early.

package/examples/dev-team/skills/bug-reporting/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: bug-reporting
+description: "Produce clear, actionable, reproducible bug reports. Use whenever a test fails or unexpected behavior is discovered during verification."
+---
+
+# Bug Reporting
+
+Write bug reports that are precise, reproducible, and actionable — so Developer can fix the issue without asking clarifying questions.
+
+## Philosophy
+
+A bug you can't reproduce isn't a bug report — it's noise. A bug without context is a puzzle that wastes Developer's time. Every minute Developer spends understanding your report is a minute they're not fixing the bug.
+
+The goal: Developer reads the report and immediately knows what's wrong, where to look, and how to verify the fix.
+
+## When to Use
+
+- Whenever an acceptance test fails
+- When you observe unexpected behavior during any testing
+- When regression tests reveal broken existing functionality
+
+## Bug Report Format
+
+```markdown
+## Bug: [Short descriptive title]
+
+**ID**: BUG-[number]
+**Severity**: Critical | Major | Minor
+**Requirement**: [which PRD requirement this violates, if applicable]
+**Found in**: [acceptance test name / manual exploration]
+
+### Environment
+- [relevant environment details: OS, runtime version, config]
+
+### Steps to Reproduce
+1. [Precise first step — include exact commands, inputs, clicks]
+2. [Second step]
+3. [Third step]
+
+### Expected Behavior
+[What should happen according to the requirement/acceptance criteria]
+
+### Actual Behavior
+[What actually happened — be specific]
+
+### Evidence
+```
+[Error output, log snippet, or test output]
+```
+
+### Notes
+[Any additional context: does it happen consistently? any patterns?]
+```
+
+## Severity Guide
+
+- **Critical**: Feature is completely broken. Core functionality doesn't work. Data loss. Crash.
+- **Major**: Feature partially works but an important scenario fails. Significant usability issue. Blocks acceptance.
+- **Minor**: Feature works but with cosmetic issues, minor inconsistencies, or edge cases. Doesn't block acceptance.
+
+## Guidelines
+
+### Be Precise
+- ❌ "Search doesn't work"
+- ✅ "Searching for 'billing' in the project search box returns 0 results, but 3 projects contain 'billing' in their names"
+
+### Be Reproducible
+- Include EXACT inputs, not paraphrased ones
+- Specify the order of steps — it matters
+- Note if the bug is intermittent and under what conditions
+
+### Be Minimal
+- Find the shortest reproduction path
+- Remove unnecessary steps
+- If a bug happens on step 10 of a flow, check if it also happens in a simpler scenario
+
+### Separate Bugs
+- One bug per report. Don't bundle "I found 3 issues" into one report.
+- If bugs are related, note the relationship but file separately.
+
+### Don't Diagnose
+- Report what you observed, not what you think the cause is
+- ❌ "The database query is probably wrong"
+- ✅ "Searching for 'billing' returns 0 results when 3 matching projects exist"
+- Developer knows the code. Trust them to find the cause from good symptoms.
+
+## Anti-Patterns
+
+- **The novel**: 2 pages of context before getting to the bug. Put the bug first, context after.
+- **The guess**: "I think it might fail if..." — either reproduce it or don't report it.
+- **The drive-by**: "Something seems off with search." What seems off? Compared to what?
+- **The combo**: "Search doesn't work, also the button color is wrong, and the loading is slow." Three separate bugs.

package/examples/dev-team/skills/codebase-mapping/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: codebase-mapping
+description: "Read and understand a codebase's architecture, modules, boundaries, and conventions. Use when onboarding to a new project, before designing any implementation, or when the codebase has evolved significantly since last review."
+---
+
+# Codebase Mapping
+
+Deeply read and understand a codebase to build an accurate mental model of its architecture, enabling informed design decisions.
+
+## Philosophy
+
+> "The best code you can write now is code you'll discard in a couple of years time." — Martin Fowler (Sacrificial Architecture)
+
+Understanding what exists is the prerequisite to designing what should exist. Most architectural mistakes happen when designers work from imagination rather than from reality.
+
+> "A poor architecture is a major contributor to the growth of cruft — elements of the software that impede the ability of developers to understand the software." — Martin Fowler
+
+Your job is to map the cruft as well as the clean parts. Both inform design decisions.
+
+## When to Use
+
+- First time working on a codebase
+- Before designing any non-trivial implementation
+- When you suspect the codebase has drifted from the last documented architecture
+- After a major refactor or feature addition
+
+## Process
+
+### Step 1: Structural Survey
+
+Start with the broadest view and zoom in:
+
+1. **Project root** — What's in the top-level directory? Build system? Monorepo? Single package?
+2. **Source tree** — Map the directory structure. What's the organizational principle? (by feature? by layer? by domain?)
+3. **Entry points** — Where does execution start? CLI entry, HTTP server bootstrap, main function, index exports
+4. **Dependencies** — What external libraries are used? What do they tell you about architectural choices?
+5. **Build & config** — How is the project built, tested, deployed? What environment variables matter?
+
+### Step 2: Module Boundary Analysis
+
+For each major module/directory:
+
+1. **Responsibility** — What is this module's job? (one sentence)
+2. **Public interface** — What does it export? What do other modules use from it?
+3. **Internal structure** — How is it organized internally?
+4. **Dependencies** — What other modules does it depend on? (draw the dependency graph)
+5. **Boundary integrity** — Is the boundary clean? Or do other modules reach into its internals?
+
+**Red flags to note:**
+- Circular dependencies between modules
+- A module that depends on everything (god module)
+- A module that everything depends on (hidden coupling)
+- Files that don't belong in their directory
+- Duplicated logic across modules
+
+### Step 3: Pattern Recognition
+
+Identify the recurring patterns in the codebase:
+
+- **Naming conventions** — How are files, functions, classes, variables named?
+- **Architectural patterns** — MVC? Event-driven? Plugin architecture? Layered?
+- **Error handling** — How are errors propagated? Custom error types? Error codes?
+- **Data flow** — How does data move through the system? Transforms? Validations?
+- **State management** — Where is state held? How is it mutated?
+- **Testing patterns** — What's the test structure? What frameworks? What's the coverage strategy?
+
+### Step 4: Identify Architectural Decisions
+
+Document the implicit decisions embedded in the code:
+
+- Why was this technology chosen over alternatives?
+- Why is the code organized this way?
+- What constraints does this architecture impose on future changes?
+- Where has the architecture been compromised (tech debt)?
+
+### Step 5: Produce the Architecture Map
+
+```markdown
+# Architecture Map: [Project Name]
+
+## Overview
+One paragraph summary of the system's architecture.
+
+## Structure
+Directory tree with annotations explaining each major directory.
+
+## Module Map
+For each module:
+- **Purpose**: one sentence
+- **Public API**: key exports/interfaces
+- **Dependencies**: what it uses
+- **Dependents**: what uses it
+
+## Dependency Graph
+ASCII or description of module dependency relationships.
+
+## Patterns & Conventions
+- Naming: [patterns]
+- Error handling: [approach]
+- Data flow: [description]
+- Testing: [approach]
+
+## Architectural Decisions
+Key decisions and their rationale (known or inferred).
+
+## Technical Debt
+Known compromises, hacks, TODOs, and boundary violations.
+
+## Hotspots
+Areas of high complexity or frequent change that need extra care.
+```
+
+## Guidelines
+
+- **Read code, don't skim it.** Skimming leads to wrong mental models. Read the actual implementations of key functions, not just their signatures.
+- **Follow the data.** When in doubt about architecture, trace how data flows from input to output. Data flow reveals the true architecture, regardless of what the directory structure suggests.
+- **Respect what exists.** The current architecture was built by people who had reasons. Understand those reasons before judging.
+- **Note the drift.** Reality drifts from intent. Document where the code has diverged from its apparent design.
+- **Keep it updated.** An outdated architecture map is worse than none — it creates false confidence.

package/examples/dev-team/skills/implementation-planning/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: implementation-planning
+description: "Design a concrete implementation plan from requirements, specifying which files, modules, functions, and classes to create or modify. Use after receiving requirements from PM and having an up-to-date codebase map."
+---
+
+# Implementation Planning
+
+Translate product requirements into a concrete, file-level implementation plan that Developer can execute without guessing.
+
+## Philosophy
+
+> "Design is there to enable you to keep changing the software easily in the long term." — Kent Beck (via Martin Fowler)
+
+Your plan should make the system simpler or no more complex. Every new file, class, or abstraction must justify its existence against the alternative of reusing or extending what already exists.
+
+> "Planned design has faults... it's impossible to think through all the issues that you need to deal with when you are programming." — Martin Fowler (Is Design Dead?)
+
+Accept that your plan will be imperfect. Design at the right level of detail: specific enough that Developer knows WHERE to put code, flexible enough that they can handle surprises.
+
+> Google's rule: "Design for ~10X growth, but plan to rewrite before ~100X." — Jeff Dean
+
+Don't over-engineer. Design for the current need with extension points for the foreseeable future.
+
+## When to Use
+
+- After receiving requirements from PM (with acceptance criteria)
+- After updating your codebase map for the affected areas
+- When a requirement reveals that the current architecture needs revision
+
+## Process
+
+### Step 1: Understand the Requirement
+
+Read the PRD completely. Verify you understand:
+- What user-visible behavior changes
+- What the acceptance criteria are
+- What the non-goals are (avoid designing for out-of-scope items)
+
+If anything is unclear, ask PM before designing.
+
+### Step 2: Survey the Affected Code
+
+Using your codebase map, identify:
+- Which existing modules are affected?
+- Which existing functions/classes need modification?
+- What can be reused or extended?
+- What would need to change to accommodate this cleanly?
+
+**Critical question: Can this be done by modifying existing code rather than creating new code?**
+
+The default AI instinct is to create new files. Resist it. Modification > creation unless there's a clear architectural reason for new code.
+
+### Step 3: Design the Change
+
+For each requirement, specify:
+
+1. **Files to modify** — Which existing files change, and what changes in each
+2. **Files to create** (if truly necessary) — Where they go, what they contain, why a new file is needed
+3. **Functions/classes** — New or modified, with signatures and brief behavior description
+4. **Interfaces** — How new code connects to existing code (function calls, events, imports)
+5. **Data flow** — How data moves through the new/modified components
+
+### Step 4: Analyze Trade-offs
+
+For non-trivial decisions, document alternatives:
+
+```markdown
+### Decision: [what]
+
+**Option A**: [description]
+- ✅ Pro: [advantage]
+- ❌ Con: [disadvantage]
+
+**Option B**: [description]
+- ✅ Pro: [advantage]
+- ❌ Con: [disadvantage]
+
+**Choice**: Option [X] because [reason]
+```
+
+### Step 5: Check for Entropy
+
+Before finalizing, audit your plan against these questions:
+
+- [ ] Does this plan add more code than necessary?
+- [ ] Could any new file be merged into an existing one without violating boundaries?
+- [ ] Does this create any new dependencies between modules that didn't exist before?
+- [ ] Does this duplicate any logic that already exists elsewhere?
+- [ ] Does this respect existing naming conventions and patterns?
+- [ ] Would this plan make sense to a developer who knows the codebase but hasn't seen the requirement?
+
+If you answer "yes" to the first four questions, revise the plan.
+
+### Step 6: Produce the Implementation Plan
+
+```markdown
+# Implementation Plan: [Feature Title]
+
+**Requirement**: [link to PRD or brief summary]
+**Architect**: [name]
+**Status**: Draft | Reviewed | Approved
+
+## Summary
+One paragraph describing the approach.
+
+## Changes
+
+### 1. [Task title]
+**File**: `path/to/existing/file.js`
+**Action**: Modify
+**Changes**:
+- Add function `doThing(input: Type): ReturnType` — [what it does]
+- Modify function `existingFunc` to call `doThing` when [condition]
+
+### 2. [Task title]
+**File**: `path/to/new/file.js` (NEW)
+**Justification**: [why a new file is needed]
+**Contents**:
+- Class `ThingProcessor` — [responsibility]
+  - `process(data): Result` — [behavior]
+  - `validate(data): boolean` — [behavior]
+
+## Data Flow
+[How data moves through the changes]
+
+## Trade-off Decisions
+[Document any non-obvious choices]
+
+## Risks & Technical Debt
+- [Known risk and mitigation]
+- [Any tech debt this introduces, with plan to address]
+
+## Task Order
+Recommended implementation sequence:
+1. [Task] — because [dependency reason]
+2. [Task] — depends on #1
+3. [Task] — independent, can parallel with #2
+```
+
+## Anti-Patterns
+
+- **The "create new everything" plan**: 5 new files for a feature that could be 30 lines in an existing module
+- **The architecture astronaut**: Introducing abstractions, interfaces, and patterns for a one-off feature
+- **The hand-wave plan**: "Add search to the dashboard" without specifying which file, function, or integration point
+- **The over-specified plan**: Dictating variable names and loop structures — that's Developer's domain
+- **The assumption plan**: Designing without reading the affected code first

package/examples/dev-team/skills/prd-generation/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: prd-generation
+description: "Produce a structured Product Requirements Document from clarified requirements. Use after requirement clarification is complete and the team needs a formal handoff document for Architect and QA."
+---
+
+# PRD Generation
+
+Produce a structured, actionable Product Requirements Document that serves as the single source of truth for Architect (design), Developer (implementation), and QA (verification).
+
+## Philosophy
+
+> "A functional specification describes how a product will work entirely from the user's perspective. It doesn't care how the thing is implemented. It talks about features." — Joel Spolsky
+
+The PRD is NOT a technical design document. It describes WHAT the product should do, not HOW it should be built. It is the contract between the user's intent and the team's execution.
+
+> "Shaped work is rough, solved, and bounded." — Shape Up
+
+The PRD should be detailed enough that no one has to guess what to build, but abstract enough that the Architect has room to design the best solution.
+
+## When to Use
+
+- After requirements have been clarified (use `requirement-clarification` skill first)
+- When handing off work to Architect and QA
+- When documenting a feature for future reference
+
+## PRD Structure
+
+```markdown
+# PRD: [Feature/Project Title]
+
+**Author**: [PM agent name]
+**Status**: Draft | Review | Approved
+**Priority**: P0 | P1 | P2
+**Date**: [date]
+
+---
+
+## 1. Background & Motivation
+
+Why are we doing this? What problem does this solve? What user pain does it address?
+Include any relevant context: user feedback, market pressure, technical debt.
+
+Keep it concise — 2-3 paragraphs max.
+
+## 2. Goals
+
+3 clear, orthogonal goals. Each goal should be independently valuable.
+
+- **Goal 1**: [measurable outcome]
+- **Goal 2**: [measurable outcome]
+- **Goal 3**: [measurable outcome]
+
+## 3. User Scenarios
+
+For each distinct user journey, write a concrete scenario:
+
+### Scenario 1: [Name]
+**User**: [who]
+**Context**: [when/where]
+**Flow**:
+1. User does X
+2. System responds with Y
+3. User sees Z
+**Edge cases**: [what if...]
+
+### Scenario 2: [Name]
+...
+
+## 4. Requirements
+
+### 4.1 Functional Requirements
+
+| ID | Priority | Requirement | Acceptance Criteria |
+|----|----------|-------------|---------------------|
+| F1 | P0 | [what] | Given [x], when [y], then [z] |
+| F2 | P0 | [what] | Given [x], when [y], then [z] |
+| F3 | P1 | [what] | Given [x], when [y], then [z] |
+
+### 4.2 Non-Functional Requirements
+
+| ID | Category | Requirement |
+|----|----------|-------------|
+| NF1 | Performance | [specific measurable target] |
+| NF2 | Compatibility | [specific constraint] |
+
+## 5. Non-Goals (Out of Scope)
+
+Explicit list of what we are NOT doing and why.
+
+- ❌ [thing]: [reason]
+
+## 6. Dependencies & Interactions
+
+How this feature interacts with existing system capabilities.
+
+- [existing feature] → [how it's affected]
+
+## 7. Open Questions
+
+Unresolved items that need answers before or during implementation.
+
+- [ ] [question] — owner: [who should answer]
+
+## 8. Appendix (Optional)
+
+Supporting data, mockups, research, competitive analysis.
+```
+
+## Guidelines
+
+### For Architect (Design Consumer)
+- Requirements should describe WHAT, never HOW
+- Include enough context about existing system behavior for the Architect to make informed design decisions
+- Flag areas where you anticipate architectural complexity: "This interacts with the notification system in non-obvious ways"
+
+### For QA (Verification Consumer)
+- Every functional requirement MUST have acceptance criteria
+- Acceptance criteria must be verifiable without reading source code
+- Include edge cases and error scenarios explicitly — don't leave them for QA to "figure out"
+- Describe the expected behavior precisely: exact error messages, status codes, UI states
+
+### For the User (Alignment Consumer)
+- The PRD should be readable by the user who requested the feature
+- They should be able to confirm "yes, this is what I want" or "no, you misunderstood"
+- Avoid jargon. Describe behavior in terms the user understands.
+
+## Quality Checklist
+
+Before marking a PRD as ready for review:
+
+- [ ] Every requirement has acceptance criteria
+- [ ] At least one concrete user scenario exists
+- [ ] Non-goals are explicitly stated
+- [ ] Dependencies with existing features are documented
+- [ ] Open questions have assigned owners
+- [ ] A non-technical person can understand what will be built
+- [ ] Priority is assigned to every requirement (P0/P1/P2)
+
+## Anti-Patterns
+
+- **The novel**: 10-page PRDs that no one reads. Be concise. If it's too long, split into multiple PRDs.
+- **The wishlist**: Requirements without priorities. Everything is P0 means nothing is P0.
+- **The blueprint**: Specifying database schemas, API formats, or code structure. That's the Architect's job.
+- **The assumption**: "Obviously the search should be instant" — nothing is obvious. Write it down.
+- **The orphan**: A PRD with no scenarios. If you can't describe a user doing it, maybe they don't need it.