opencode-agile-agent 1.0.1 → 1.0.2

package/templates/.opencode/skills/brainstorming/SKILL.md

@@ -1,255 +1,39 @@
 ---
 name: brainstorming
-description: Socratic questioning and discovery techniques for exploring ideas and requirements.
-version: 1.0.0
+description: Explore fuzzy requests with Socratic questions, tradeoffs, and a recommended direction.
 ---
 
 # Brainstorming
 
-Socratic questioning and discovery techniques for exploring ideas and clarifying requirements.
+## Philosophy
+Questions shape the solution. Discovery should narrow the space before anyone commits to a path.
 
-## The Socratic Method
+## Use When
+- The request is ambiguous or the scope is not settled.
+- There are multiple valid approaches and a default choice is needed.
+- You need to surface assumptions before planning or coding.
 
-Ask questions to guide discovery rather than providing answers.
+## Core Moves
+- Ask to uncover the problem, audience, constraints, and success criteria.
+- Separate options from decisions.
+- Reflect back what you heard before moving forward.
+- Keep the conversation moving; avoid endless exploration.
 
-### Core Questions
+## Default Moves
+- Ask 3-5 targeted questions, not a full interview.
+- Compare 2-3 options and recommend one default.
+- Record the open questions that remain.
 
-1. **What is the problem?**
-   - What are you trying to solve?
-   - Who has this problem?
-   - Why does it matter?
+## Anti-Patterns
+- Leading questions, yes/no traps, hidden assumptions, and jumping to architecture too early.
 
-2. **What are the constraints?**
-   - What's the timeline?
-   - What's the budget?
-   - What technical limitations exist?
+## Variation
+- Use 3-question mode for simple requests.
+- Use 5-whys for bugs and root-cause conversations.
+- Use a tradeoff matrix when the decision is architectural.
 
-3. **What does success look like?**
-   - How will you measure success?
-   - What's the definition of done?
-   - What would failure look like?
+## Output
+- Return a crisp problem statement, a small set of options, a recommendation, and unresolved questions.
 
-## Question Frameworks
-
-### 5 Whys
-
-Dig deeper into root causes:
-
-```
-Problem: Users aren't completing checkout
-
-Why? → Form is too long
-Why? → We're asking for too much information
-Why? → We want complete user profiles
-Why? → Marketing wants demographic data
-Why? → To improve targeting
-
-Root cause: Marketing needs vs. UX needs conflict
-```
-
-### SCAMPER
-
-Explore alternatives:
-
-| Question | Prompt |
-|----------|--------|
-| **S**ubstitute | What can be replaced? |
-| **C**ombine | What can be merged? |
-| **A**dapt | What can be adjusted? |
-| **M**odify | What can be changed? |
-| **P**ut to other use | What else can it do? |
-| **E**liminate | What can be removed? |
-| **R**everse | What can be inverted? |
-
-### Six Thinking Hats
-
-Explore from different perspectives:
-
-| Hat | Focus |
-|-----|-------|
-| **White** | Facts and data |
-| **Red** | Emotions and feelings |
-| **Black** | Risks and problems |
-| **Yellow** | Benefits and value |
-| **Green** | Creativity and alternatives |
-| **Blue** | Process and control |
-
-## Discovery Process
-
-### Phase 1: Understand the Request
-
-```markdown
-Initial request: "Build a dashboard"
-
-Questions to ask:
-- Who will use this dashboard?
-- What decisions will they make from it?
-- What data do they need?
-- How often will they use it?
-- What devices will they use?
-```
-
-### Phase 2: Explore Options
-
-```markdown
-Options for dashboard:
-1. Real-time monitoring dashboard
-2. Analytics dashboard with charts
-3. Task management dashboard
-4. Executive summary dashboard
-
-Trade-offs:
-- Real-time vs. historical data
-- Simple vs. detailed
-- Mobile vs. desktop priority
-```
-
-### Phase 3: Define Scope
-
-```markdown
-In Scope:
-- [Feature 1]
-- [Feature 2]
-
-Out of Scope:
-- [Feature X]
-- [Feature Y]
-
-MVP:
-- [Minimum viable feature set]
-```
-
-### Phase 4: Validate Understanding
-
-```markdown
-"So what I'm hearing is:
-- You need [X]
-- For [audience]
-- To solve [problem]
-- With [constraints]
-
-Is that correct?"
-```
-
-## Question Templates
-
-### For New Features
-
-```markdown
-1. What problem does this solve?
-2. Who is the target user?
-3. How are they solving this today?
-4. What would make this feature a success?
-5. What are the must-haves vs. nice-to-haves?
-6. What's the timeline?
-7. Are there any technical constraints?
-8. Are there any design preferences?
-```
-
-### For Bug Fixes
-
-```markdown
-1. What's the expected behavior?
-2. What's the actual behavior?
-3. When did this start happening?
-4. Can you reproduce it reliably?
-5. What steps reproduce it?
-6. What have you tried to fix it?
-7. Who is affected by this?
-8. How urgent is this?
-```
-
-### For Performance Issues
-
-```markdown
-1. What's slow?
-2. How slow is it? (measure)
-3. When is it slow?
-4. Has it always been slow?
-5. What changed recently?
-6. What's the target performance?
-7. What metrics matter most?
-```
-
-### For Architecture Decisions
-
-```markdown
-1. What are we trying to achieve?
-2. What are the constraints?
-3. What are the options?
-4. What are the trade-offs of each?
-5. What's the impact of each option?
-6. How reversible is this decision?
-7. What's the cost of waiting?
-```
-
-## Facilitation Techniques
-
-### Dot Voting
-
-```markdown
-Options:
-- Option A •••• (4 votes)
-- Option B •• (2 votes)
-- Option C ••• (3 votes)
-
-→ Proceed with Option A
-```
-
-### Impact/Effort Matrix
-
-```
-         High Impact
-              │
-   Quick Wins │ Major Projects
-──────────────┼──────────────
-  Fill-ins    │ Money Pits
-              │
-         Low Impact
-    Low Effort      High Effort
-```
-
-### Affinity Mapping
-
-```markdown
-Group related ideas:
-
-[Performance]     [Security]      [UX]
-- Load time      - Auth          - Navigation
-- Caching        - Encryption    - Responsive
-- CDN            - Validation    - Accessibility
-```
-
-## Anti-Patterns to Avoid
-
-### Leading Questions
-
-```
-❌ "Don't you think we should use React?"
-✅ "What frontend framework are you considering?"
-```
-
-### Yes/No Questions
-
-```
-❌ "Do you need authentication?"
-✅ "Tell me about your authentication requirements."
-```
-
-### Assumptions
-
-```
-❌ "I assume you want dark mode."
-✅ "Do you have preferences for the visual theme?"
-```
-
-### Solutionizing
-
-```
-❌ "We should build it with microservices."
-✅ "What are your scalability requirements?"
-```
-
----
-
-**Good questions lead to better solutions.**
+## Remember
+Good questions make later specs smaller and clearer.

package/templates/.opencode/skills/clean-code/SKILL.md

@@ -1,351 +1,39 @@
 ---
 name: clean-code
-description: Global coding standards and best practices. All agents should follow these principles.
-version: 1.0.0
+description: Apply global coding standards for readable, maintainable, defensive code.
 ---
 
-# Clean Code - Global Standards
+# Clean Code
 
-Universal coding principles that apply across all domains and languages.
+## Philosophy
+Code should read like intent, not a puzzle. Clarity beats cleverness.
 
-## The 5 Laws of Elegant Code
+## Use When
+- You are writing or reviewing code in any language.
+- The implementation needs readability, safety, or structure improvements.
+- You want a universal standard before more specific domain skills apply.
 
-### 1. Guard Clauses First
+## Core Moves
+- Use guard clauses to handle unhappy paths early.
+- Validate and transform at the boundary, then trust the result inside.
+- Prefer pure functions unless mutation is clearly owned and contained.
+- Fail loud on impossible states instead of hiding them.
+- Use names that explain intent without extra comments.
 
-Handle unhappy paths at the beginning of functions. Return early.
+## Default Moves
+- Return early instead of nesting deeply.
+- Keep side effects explicit and local.
+- Choose the simplest code that makes the path obvious.
 
-```typescript
-// ❌ Nested conditionals
-function process(user) {
-  if (user) {
-    if (user.isActive) {
-      if (user.hasPermission) {
-        return doSomething(user);
-      }
-    }
-  }
-  return null;
-}
+## Anti-Patterns
+- Nested conditionals, scattered validation, silent fallback, clever one-liners, and vague names.
 
-// ✅ Guard clauses
-function process(user) {
-  if (!user) return null;
-  if (!user.isActive) return null;
-  if (!user.hasPermission) return null;
-  
-  return doSomething(user);
-}
-```
+## Variation
+- Be stricter at boundaries and more compact in tiny helpers.
+- Allow controlled mutation in owned state, but keep transforms pure.
 
-### 2. Parsed State at Boundaries
+## Output
+- Return the smallest set of fixes that makes the code easier to read and harder to misuse.
 
-Validate and transform input at the edge. Trust inside.
-
-```typescript
-// ❌ Checking everywhere
-function updateEmail(email) {
-  if (!isValidEmail(email)) throw new Error('Invalid');
-  // ... logic
-}
-
-function saveUser(user) {
-  if (!isValidEmail(user.email)) throw new Error('Invalid');
-  // ... logic
-}
-
-// ✅ Parse once, trust everywhere
-type Email = string & { readonly __brand: unique symbol };
-
-function parseEmail(input: string): Email | Error {
-  if (!emailRegex.test(input)) {
-    return new Error('Invalid email');
-  }
-  return input as Email;
-}
-
-// Now Email is guaranteed valid
-function updateEmail(email: Email) {
-  // No validation needed - Email type guarantees validity
-}
-```
-
-### 3. Pure Functions
-
-Functions should be predictable. Same input → same output. No side effects.
-
-```typescript
-// ❌ Impure - depends on external state
-let total = 0;
-function addToTotal(amount) {
-  total += amount;
-  return total;
-}
-
-// ✅ Pure - predictable
-function addToTotal(currentTotal: number, amount: number): number {
-  return currentTotal + amount;
-}
-```
-
-### 4. Fail Loud
-
-Invalid states should throw errors, not silently continue.
-
-```typescript
-// ❌ Silent failure
-function getConfig(key) {
-  return config[key] || null; // Hides the problem
-}
-
-// ✅ Fail loud
-function getConfig(key: keyof Config): ConfigValue {
-  const value = config[key];
-  if (value === undefined) {
-    throw new Error(`Missing required config: ${key}`);
-  }
-  return value;
-}
-```
-
-### 5. Readability First
-
-Code reads like a sentence. Names are documentation.
-
-```typescript
-// ❌ Unclear
-const d = new Date();
-const x = users.filter(u => u.a).map(u => u.n);
-
-// ✅ Readable
-const now = new Date();
-const activeUserNames = users
-  .filter(user => user.isActive)
-  .map(user => user.name);
-```
-
-## Naming Conventions
-
-### Variables
-
-```typescript
-// Use descriptive names
-const users = [...]; // Good
-const userList = [...]; // Redundant
-const data = [...]; // Too vague
-
-// Boolean names should read naturally
-const isActive = true;
-const hasPermission = false;
-const canEdit = true;
-
-// Avoid negatives in names
-const isNotActive = false; // Confusing: !isNotActive
-const isDisabled = false; // Better: !isDisabled
-```
-
-### Functions
-
-```typescript
-// Functions should describe actions
-function getUser() { } // Good
-function userData() { } // Is it a getter or setter?
-
-// Boolean functions should be questions
-function isValid() { } // Good
-function validate() { } // Sounds like it throws
-
-// Event handlers should describe what happens
-function handleSubmit() { } // Good
-function onClick() { } // Too generic
-```
-
-### Classes
-
-```typescript
-// Classes should be nouns
-class User { } // Good
-class UserManager { } // Good
-class CreateUser { } // Sounds like a function
-```
-
-## Function Guidelines
-
-### Single Responsibility
-
-```typescript
-// ❌ Does too many things
-function processOrder(order) {
-  validateOrder(order);
-  calculateTotal(order);
-  chargePayment(order);
-  sendConfirmation(order);
-  updateInventory(order);
-}
-
-// ✅ One thing, well
-function processOrder(order: Order): ProcessResult {
-  return pipe(
-    validateOrder,
-    calculateTotal,
-    chargePayment,
-    sendConfirmation,
-    updateInventory
-  )(order);
-}
-```
-
-### Small Functions
-
-```typescript
-// ❌ 100+ line function
-function doEverything() {
-  // 100 lines of code
-}
-
-// ✅ Small, focused functions
-function validateInput(input: Input): ValidationResult {
-  // 5-10 lines
-}
-
-function processData(data: Data): ProcessedData {
-  // 5-10 lines
-}
-```
-
-### Avoid Side Effects
-
-```typescript
-// ❌ Modifies input
-function addItem(cart, item) {
-  cart.items.push(item);
-  return cart;
-}
-
-// ✅ Returns new value
-function addItem(cart: Cart, item: Item): Cart {
-  return {
-    ...cart,
-    items: [...cart.items, item]
-  };
-}
-```
-
-## Code Organization
-
-### File Structure
-
-```
-src/
-├── components/     # UI components
-├── hooks/          # Custom hooks
-├── services/       # Business logic
-├── utils/          # Pure utilities
-├── types/          # TypeScript types
-└── constants/      # Constants
-```
-
-### Import Order
-
-```typescript
-// 1. External dependencies
-import { useState, useEffect } from 'react';
-import { z } from 'zod';
-
-// 2. Internal modules
-import { UserService } from '@/services/user';
-import { Button } from '@/components/ui';
-
-// 3. Types
-import type { User } from '@/types';
-
-// 4. Constants
-import { MAX_RETRIES } from './constants';
-```
-
-## Comments
-
-### When to Comment
-
-```typescript
-// ✅ Explain WHY, not WHAT
-// Using exponential backoff to avoid overwhelming the server
-const delay = Math.pow(2, retryCount) * 1000;
-
-// ✅ Document complex algorithms
-// Using Fisher-Yates shuffle for unbiased randomization
-function shuffle(array) { ... }
-
-// ✅ Add TODOs with context
-// TODO(#123): Remove after migrating to new API
-```
-
-### When NOT to Comment
-
-```typescript
-// ❌ Explains the obvious
-// Loop through users
-for (const user of users) { }
-
-// ❌ Outdated comment
-// This function does X (but it actually does Y now)
-
-// ❌ Commented-out code
-// function oldFunction() { ... }
-```
-
-## Error Handling
-
-### Use Specific Errors
-
-```typescript
-// ❌ Generic error
-throw new Error('Something went wrong');
-
-// ✅ Specific error
-throw new ValidationError('Email is invalid', { field: 'email' });
-```
-
-### Handle Errors at Boundaries
-
-```typescript
-// ❌ Silent catch
-try {
-  doSomething();
-} catch (e) {
-  // Do nothing
-}
-
-// ✅ Log and handle
-try {
-  doSomething();
-} catch (error) {
-  logger.error('Failed to do something', { error });
-  throw new ServiceError('Operation failed', { cause: error });
-}
-```
-
-## Testing Principles
-
-### Test Behavior, Not Implementation
-
-```typescript
-// ❌ Tests implementation
-expect(component.state.count).toBe(1);
-
-// ✅ Tests behavior
-expect(screen.getByText('Count: 1')).toBeInTheDocument();
-```
-
-### Use Descriptive Test Names
-
-```typescript
-// ❌ Vague
-test('user', () => { ... });
-
-// ✅ Descriptive
-test('should create user with valid email', () => { ... });
-```
-
----
-
-**These principles apply to all code, regardless of language or domain.**
+## Remember
+Readable code is a feature, not a luxury.