opencode-agile-agent 1.0.1 → 1.0.3

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

@@ -1,512 +1,40 @@
 ---
 name: code-philosophy
-description: Internal logic and data flow philosophy (The 5 Laws of Elegant Defense). Understand deeply to ensure code guides data naturally and prevents errors. Use when writing, reviewing, or refactoring code.
+description: Reason about data flow, invariants, failure posture, and ownership before changing code.
 ---
 
-# Code Philosophy: The 5 Laws of Elegant Defense
+# Code Philosophy
 
-Internal logic and data flow philosophy that ensures code guides data naturally and prevents errors before they happen.
+## Philosophy
+Good code guides data through deliberate boundaries and makes illegal states hard to reach.
 
-## Philosophy Overview
+## Use When
+- You are reviewing or refactoring logic and state flow.
+- The design has unclear ownership, failure modes, or boundary handling.
+- The question is about how the system should think, not just how it should look.
 
-> **Code is written once but read many times.**
-> 
-> Every line must justify its existence in terms of **clarity**, **correctness**, and **performance**.
+## Core Moves
+- Gate untrusted data at the edge.
+- Trust parsed state inside a module or layer.
+- Make side effects explicit and owned.
+- Prefer simple invariants over repeated defensive checks.
+- Expose impossible states quickly and clearly.
 
-These 5 laws form the foundation of defensive programming that produces maintainable, robust, and readable code.
+## Default Moves
+- Validate input once and reuse the trusted result.
+- Use explicit state transitions instead of hidden mutation.
+- Separate control flow from data transformation where possible.
 
----
-
-## Law 1: Guard Clauses — Handle Unhappy Path First
-
-### The Problem
-
-Traditional nested conditionals bury the happy path deep inside multiple levels of indentation, making code hard to read and maintain.
-
-### The Solution
-
-Reject invalid states at the **top** of every function with early returns. The happy path should be the last thing you see, not buried in an `else` branch.
-
-### Examples
-
-```typescript
-// ❌ BAD — deeply nested, hard to follow
-function process(data: Data | null) {
-  if (data) {
-    if (data.items.length > 0) {
-      if (data.isValid) {
-        // ... actual logic deep inside
-        return transform(data);
-      }
-    }
-  }
-  return null;
-}
-
-// ✅ GOOD — guard at the top, logic flows clearly
-function process(data: Data | null) {
-  if (!data) return null;
-  if (data.items.length === 0) return null;
-  if (!data.isValid) return null;
-  
-  // ... actual logic at the top level
-  return transform(data);
-}
-```
-
-### Benefits
-
-- **Readability**: Main logic at top level, not nested
-- **Early Exit**: Fail fast, no deep nesting
-- **Clear Intent**: Each guard shows what we're checking
-
-### Checklist
-
-- [ ] Are all edge cases (null, empty, unauthorized) handled at the top?
-- [ ] Is the happy path visible without scrolling?
-- [ ] Can I understand the function's purpose from the guards?
-
----
-
-## Law 2: Parsed State — Trust Your Types at the Boundary
-
-### The Problem
-
-Untrusted data (API responses, route params, user input) used directly throughout the codebase leads to scattered defensive checks and type uncertainty.
-
-### The Solution
-
-Validate and parse untrusted data **at the entry point**. Once inside the system, types should be trusted — no defensive `typeof` checks scattered throughout.
-
-### Examples
-
-```typescript
-// ❌ BAD — raw API data used directly everywhere
-const id = route.params.id; // string | string[]
-const user = await api.get(`/users/${id}`); // any
-// ... later in the code
-if (typeof user.name === 'string') { // defensive check
-  displayName.value = user.name;
-}
-
-// ✅ GOOD — parse at the boundary, use confidently
-const id = String(route.params.id); // parsed to string
-
-interface User {
-  id: string;
-  name: string;
-  email: string;
-}
-
-const user = await api.get<User>(`/users/${id}`); // typed
-// ... later in the code
-displayName.value = user.name; // confident, no check needed
-```
-
-### With Validation Libraries
-
-```typescript
-import { z } from 'zod';
-
-// Define schema at the boundary
-const UserSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  email: z.string().email(),
-  age: z.number().min(0).max(150).optional(),
-});
-
-// Parse and validate at entry point
-function handleApiResponse(data: unknown): User {
-  return UserSchema.parse(data); // throws on invalid
-}
-
-// Now use confidently everywhere
-const user = handleApiResponse(rawData);
-console.log(user.name); // type-safe, no checks needed
-```
-
-### Benefits
-
-- **Trust**: Once parsed, types are reliable
-- **Clarity**: No scattered `typeof` checks
-- **Safety**: Validation happens once, at the boundary
-
-### Checklist
-
-- [ ] Is all external data (API, router, events) parsed before use?
-- [ ] Are there defensive type checks that could be removed?
-- [ ] Do types accurately represent what the code expects?
-
----
-
-## Law 3: Purity — Functions Should Be Predictable
-
-### The Problem
-
-Functions that mutate external state or have hidden side effects are hard to test, debug, and reuse. You can't predict the output from the input alone.
-
-### The Solution
-
-A function that **only computes from its inputs and returns a result** — with no hidden mutations — is easy to test, debug, and reuse.
-
-### Examples
-
-```typescript
-// ❌ BAD — mutates external state as a side effect
-function applyDiscount(cart: Cart) {
-  cart.total = cart.total * 0.9; // hidden mutation
-  cart.items.forEach(item => {
-    item.discounted = true; // another mutation
-  });
-}
-
-// Usage
-applyDiscount(myCart);
-// What happened? We don't know from the call.
-// Cart is mutated somewhere else.
-
-// ✅ GOOD — returns a new value, no side effects
-function applyDiscount(total: number): number {
-  return total * 0.9;
-}
-
-function applyDiscountToCart(cart: Cart): Cart {
-  return {
-    ...cart,
-    total: applyDiscount(cart.total),
-    items: cart.items.map(item => ({ ...item, discounted: true })),
-  };
-}
-
-// Usage
-const discountedCart = applyDiscountToCart(myCart);
-// Clear: we get a new cart, original unchanged
-```
-
-### When Mutations Are OK
-
-Mutations are acceptable in **controlled, explicit** contexts:
-
-```typescript
-// ✅ OK — mutation inside Pinia action (controlled)
-export const useCartStore = defineStore('cart', () => {
-  const items = ref<CartItem[]>([]);
-  
-  function addItem(item: CartItem) {
-    items.value.push(item); // mutation in action
-  }
-  
-  return { items, addItem };
-});
-
-// ✅ OK — mutation in local state (contained)
-function setup() {
-  const count = ref(0);
-  
-  function increment() {
-    count.value++; // local mutation
-  }
-  
-  return { count, increment };
-}
-```
-
-### Benefits
-
-- **Testability**: Pure functions are trivial to test
-- **Predictability**: Same input → same output, always
-- **Reusability**: No hidden dependencies
-
-### Checklist
-
-- [ ] Do functions avoid mutating props, external refs, or store state?
-- [ ] Can I predict the output from the input alone?
-- [ ] Are side effects explicit and controlled?
-
----
-
-## Law 4: Fail Loud — Invalid States Must Scream
-
-### The Problem
-
-Silent failures cause mysterious bugs. When an invalid state is reached, the code continues with undefined or null values, leading to crashes later with useless stack traces.
-
-### The Solution
-
-When an invalid state is reached, **throw a clear descriptive error immediately**. Don't let bad data silently propagate.
+## Anti-Patterns
+- Scattered checks, stale state, hidden side effects, catch-all fallbacks, and fuzzy ownership.
 
-### Examples
+## Variation
+- Use more functional style in transformation layers.
+- Allow controlled mutation in stores or actions when the owner is clear.
+- Increase strictness as you move closer to external input.
 
-```typescript
-// ❌ BAD — silent failure, undefined propagates
-const user = store.users.find(u => u.id === id);
-doSomethingWith(user); // might crash later with useless stack trace
-
-// ✅ GOOD — fails immediately with context
-const user = store.users.find(u => u.id === id);
-if (!user) {
-  throw new Error(`User with id "${id}" not found in store`);
-}
-doSomethingWith(user); // safe, user exists
-```
-
-### With Error Boundaries
-
-```typescript
-// Component level
-<template>
-  <ErrorBoundary>
-    <UserProfile :userId="userId" />
-  </ErrorBoundary>
-</template>
-
-// Store level
-async function fetchUser(id: string): Promise<User> {
-  const response = await api.get<User>(`/users/${id}`);
-  
-  if (!response.data) {
-    throw new Error(`User ${id} not found (API returned empty)`);
-  }
-  
-  return response.data;
-}
-
-// API level
-api.interceptors.response.use(
-  response => response,
-  error => {
-    // Transform API errors to descriptive messages
-    const message = error.response?.data?.message 
-      || error.message 
-      || 'Unknown API error';
-    
-    throw new Error(`API Error: ${message}`);
-  }
-);
-```
-
-### Benefits
-
-- **Fast Feedback**: Know immediately when something is wrong
-- **Clear Context**: Error message explains what failed and why
-- **Easy Debugging**: Stack trace points to the real problem
-
-### Checklist
-
-- [ ] Do impossible/unexpected states throw descriptive errors?
-- [ ] Are errors silent or do they provide context?
-- [ ] Will debugging be easy if this fails in production?
-
----
-
-## Law 5: Readability — Code Reads Like a Sentence
-
-### The Problem
-
-Cryptic variable names, magic numbers, and complex logic make code hard to understand without extensive comments.
-
-### The Solution
-
-Variable names explain intent. Functions do one thing with one responsibility. A reader should understand what the code does **without comments**.
-
-### Examples
-
-```typescript
-// ❌ BAD — what is 'x'? what is 86400000?
-const x = Date.now() - ts > 86400000;
-if (x) {
-  // deactivate user
-}
-
-// ✅ GOOD — reads like a sentence
-const ONE_DAY_MS = 24 * 60 * 60 * 1000;
-const lastActivityAt = user.lastActivityAt;
-const isExpired = Date.now() - lastActivityAt > ONE_DAY_MS;
-
-if (isExpired) {
-  deactivateUser(user);
-}
-```
-
-### Naming Patterns
-
-```typescript
-// ❌ BAD — unclear names
-const d = getData();
-const p = process(d);
-const r = save(p);
-
-// ✅ GOOD — descriptive names
-const userData = fetchUserData();
-const processedUser = processUserData(userData);
-const savedUser = saveUserToDatabase(processedUser);
-
-// ❌ BAD — abbreviated
-const usr = getUser();
-const addr = usr.addr;
-
-// ✅ GOOD — full words
-const user = getUser();
-const address = user.address;
-```
-
-### Function Naming
-
-```typescript
-// ❌ BAD — vague
-function process(data) { ... }
-function handle(event) { ... }
-function doIt() { ... }
-
-// ✅ GOOD — specific
-function validateUserCredentials(credentials) { ... }
-function handleUserRegistration(event) { ... }
-function sendWelcomeEmail() { ... }
-```
-
-### Benefits
-
-- **Self-Documenting**: Code explains itself
-- **Easy Review**: Reviewers understand quickly
-- **Maintainable**: Future developers can modify safely
-
-### Checklist
-
-- [ ] Can a teammate understand each function's purpose from its name?
-- [ ] Are variable names self-documenting?
-- [ ] Does the code flow logically without needing comments?
-
----
-
-## Putting It All Together
-
-### Example: User Authentication
-
-```typescript
-// ❌ BAD — violates all 5 laws
-function login(data) {
-  if (data) {
-    if (data.email && data.password) {
-      const user = users.find(u => u.email === data.email);
-      if (user) {
-        if (user.password === data.password) {
-          currentUser = user;
-          return true;
-        }
-      }
-    }
-  }
-  return false;
-}
-
-// ✅ GOOD — follows all 5 laws
-interface LoginCredentials {
-  email: string;
-  password: string;
-}
-
-interface User {
-  id: string;
-  email: string;
-  passwordHash: string;
-}
-
-function login(credentials: LoginCredentials): User {
-  // Law 1: Guard clauses
-  if (!credentials.email || !credentials.password) {
-    throw new Error('Email and password are required');
-  }
-  
-  // Law 2: Parsed state (credentials already typed)
-  const user = findUserByEmail(credentials.email);
-  
-  // Law 4: Fail loud
-  if (!user) {
-    throw new Error(`User not found: ${credentials.email}`);
-  }
-  
-  const isValidPassword = verifyPassword(
-    credentials.password,
-    user.passwordHash
-  );
-  
-  if (!isValidPassword) {
-    throw new Error('Invalid password');
-  }
-  
-  // Law 3: Purity (returns user, doesn't mutate global)
-  return user;
-}
-
-// Law 5: Readability (clear names, reads like sentence)
-function findUserByEmail(email: string): User | undefined {
-  return users.find(user => user.email === email);
-}
-
-function verifyPassword(password: string, hash: string): boolean {
-  return bcrypt.compareSync(password, hash);
-}
-```
-
----
-
-## Anti-Patterns Summary
-
-| Anti-Pattern | Violates | Solution |
-|-------------|----------|----------|
-| Deeply nested conditionals | Law 1 | Guard clauses at top |
-| Scattered type checks | Law 2 | Parse at boundary |
-| Mutating props/state | Law 3 | Return new values |
-| Silent failures | Law 4 | Throw descriptive errors |
-| Cryptic names/numbers | Law 5 | Self-documenting code |
-
----
-
-## Review Checklist
-
-When reviewing code, check each law:
-
-```markdown
-## Code Philosophy Review
-
-### Law 1: Guard Clauses
-- [ ] Edge cases handled at top?
-- [ ] Happy path visible?
-- [ ] No deep nesting?
-
-### Law 2: Parsed State
-- [ ] External data parsed at entry?
-- [ ] Types trusted inside?
-- [ ] No scattered checks?
-
-### Law 3: Purity
-- [ ] No prop mutations?
-- [ ] No hidden side effects?
-- [ ] Functions predictable?
-
-### Law 4: Fail Loud
-- [ ] Invalid states throw?
-- [ ] Errors descriptive?
-- [ ] Debugging easy?
-
-### Law 5: Readability
-- [ ] Names self-documenting?
-- [ ] Logic flows clearly?
-- [ ] No magic numbers?
-```
-
----
+## Output
+- Return a boundary map, the key invariants, the failure modes, and the recommended flow.
 
 ## Remember
-
-**These laws are not rules — they are principles.**
-
-Use them to guide your thinking:
-- **When writing**: Follow them to write better code
-- **When reviewing**: Use them to identify issues
-- **When refactoring**: Apply them to improve existing code
-
-**The goal is code that is clear, correct, and performant.**
-
-These laws help you achieve that goal consistently.
+Make the correct path easier than the incorrect one.

package/templates/.opencode/skills/context-archive/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: context-archive
+description: Store completed feature context bundles in a compact archive for future reference.
+---
+
+# Context Archive
+
+## Philosophy
+Archive is memory with discipline. Preserve what mattered, remove what did not, and keep active work out of the record.
+
+## Use When
+- A feature or bug fix is complete and approved.
+- You need to store proposal, goal, spec, task, and important notes for later.
+- You need a searchable record of why a decision was made.
+- You are closing a feature loop and handing the project back to discovery.
+
+## Core Moves
+- Copy the final compact bundle into `.opencode/archive/<feature-slug>/`.
+- Preserve the approved version, not the draft history.
+- Add a short closure note only if it changes future understanding.
+- Keep archive entries small, readable, and immutable.
+
+## Default Moves
+- Use the same bundle shape as active work.
+- Name folders by feature slug, optionally with a date when repetition matters.
+- Mark archive entries read-only in practice.
+- Link back to the source feature or review result.
+
+## Anti-Patterns
+- Archiving before approval.
+- Stuffing active notes into the archive.
+- Saving huge raw logs instead of the compact bundle.
+- Losing the relationship between archive and shipped work.
+
+## Variation
+- Use one folder per feature for long-lived features.
+- Use date suffixes when the same feature is reopened.
+- Include only the minimal final state when the archive is meant as a handoff record.
+
+## Output
+- Archive path
+- Archived bundle summary
+- Closure note if needed
+- Source link or review reference
+
+## Remember
+Archive should help the next human or agent, not become another trash heap.

package/templates/.opencode/skills/context-gathering/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: context-gathering
+description: Map project state, active work, ownership, and archive-ready context before planning or proof.
+---
+
+# Context Gathering
+
+## Philosophy
+Compress the living system into a decision-ready snapshot. This skill should tell the lead what is active, who owns it, and what matters next. It should not become the code discovery layer.
+
+## Use When
+- A new request lands and the current project state is unclear.
+- You need to know what the project is doing now, who owns it, and whether there is archive-ready context.
+- You need a compact map before planning, debugging, or proving anything.
+- You need to distinguish active work from archived work.
+- You need to hand exact file discovery to `explorer-agent`.
+
+## Core Moves
+- Find the source of truth first: README, AGENTS, architecture, commands, recent commits, and active feature folders.
+- Identify the active path, owner, and current stage.
+- Separate active work from archive-ready work.
+- Capture only what changes the next decision.
+- If exact file paths or implementation patterns are needed, hand off to `explorer-agent`.
+
+## Default Moves
+- Start with top-level docs and recent changes.
+- Check for unfinished work or an active feature bundle.
+- Map ownership and dependencies at a high level.
+- Include archive status or target path when relevant.
+- Return a concise snapshot with the recommended next agent.
+
+## Anti-Patterns
+- Digging through implementation details when the question is only about project state.
+- Confusing archived history with active work.
+- Dumping raw file lists instead of a decision-ready summary.
+- Treating guesses as facts.
+
+## Variation
+- Use a quick scan for simple projects.
+- Use a deeper map when architecture or ownership is unclear.
+- Include archive pointers when a feature is complete or nearly complete.
+
+## Output
+- Project snapshot
+- Active work snapshot
+- Ownership and dependencies
+- Recommended next step
+- Archive status or target path
+
+## Remember
+If the next agent still has to rediscover the project, the context was not gathered well enough.