@kodrunhq/opencode-autopilot 1.10.0 → 1.11.0

package/assets/commands/oc-review-agents.md

@@ -0,0 +1,103 @@
+---
+description: Review and improve your project's agents.md file with structure validation and prompt quality feedback
+argument-hint: "[path-to-agents.md]"
+---
+
+Review and score the project's agents.md file. Follow every step below in order.
+
+## Step 1: Locate the agents.md file
+
+- If `$ARGUMENTS` is provided and non-empty, use that path
+- Otherwise, check `.opencode/agents.md` in the project root
+- Then check `agents.md` in the project root
+- If not found, tell the user no agents.md was found and suggest:
+  1. Create one manually
+  2. Copy a starter template from `~/.config/opencode/templates/` (available types: web-api, cli-tool, library, fullstack)
+  - Show the copy command: `cp ~/.config/opencode/templates/<type>.md .opencode/agents.md`
+  - Stop here — do not continue with the review
+
+## Step 2: Read and parse the file
+
+Read the located file and parse each agent block:
+
+- Look for level-2 headings (`## Agent:` or `## <name>`) as agent delimiters
+- For each agent, extract:
+  - **Name** — the heading text
+  - **Description** — any text immediately following the heading
+  - **System prompt** — the main instruction body for the agent
+  - **Tool permissions** — any allow/deny lists for tools
+  - **Model assignment** — any model field if present
+
+## Step 3: Validate structure (0-3 per agent)
+
+Score each agent's structure:
+
+| Points | Criterion |
+|--------|-----------|
+| +1 | Has a clear name and description |
+| +1 | Has a system prompt with specific (not generic) instructions |
+| +1 | Has explicit tool permissions (allow or deny lists) |
+
+Deductions:
+- -1 for missing description entirely
+- -1 for empty or placeholder system prompt
+- -1 for no tool configuration at all
+
+Minimum score is 0.
+
+## Step 4: Assess prompt quality (0-4 per agent)
+
+Score each agent's prompt quality:
+
+| Points | Criterion |
+|--------|-----------|
+| +1 | **Role clarity** — prompt defines WHO the agent is (role, expertise, personality) |
+| +1 | **Task specificity** — prompt defines WHAT the agent does with concrete instructions, not vague directives |
+| +1 | **Guardrails** — prompt defines what NOT to do, boundaries, or constraints |
+| +1 | **Output format** — prompt specifies HOW to format responses (structure, sections, style) |
+
+## Step 5: Check coverage for project type
+
+- Read project manifest files to detect type:
+  - `package.json` — check for framework indicators (express, fastify, next, react, vue, svelte)
+  - `pom.xml`, `build.gradle` — Java project
+  - `Cargo.toml` — Rust project
+  - `go.mod` — Go project
+  - `pyproject.toml`, `setup.py` — Python project
+- Classify as: web-api, cli-tool, library, fullstack, or unknown
+- Compare the agents found against recommended agents for that project type
+- Note missing agent roles that would benefit the project
+- Reference starter templates in `~/.config/opencode/templates/` for comparison
+
+## Step 6: Output the review
+
+Format your review exactly like this:
+
+```
+## agents.md Review
+
+**File:** {path}
+**Agents found:** {count}
+**Overall Score:** {total}/{max} ({percentage}%)
+
+### Per-Agent Assessment
+
+#### {agent-name}
+- Structure: {score}/3 — {brief notes}
+- Prompt Quality: {score}/4 — {brief notes}
+- Suggestions:
+  - {specific actionable improvement}
+
+### Coverage Analysis
+- Project type detected: {type}
+- Recommended agents for this type: {list}
+- Missing: {list with brief explanation of why each would help}
+- Starter template: {if type is web-api, cli-tool, library, or fullstack: `Run cat ~/.config/opencode/templates/{type}.md to see a reference`; otherwise: `No starter template available for this project type`}
+
+### Top 3 Improvements
+1. {Most impactful improvement with specific guidance}
+2. {Second most impactful improvement}
+3. {Third most impactful improvement}
+```
+
+The overall score is the sum of all per-agent structure + prompt quality scores. The max is `agent_count * 7`. Report the percentage rounded to the nearest whole number.

package/assets/skills/coding-standards/SKILL.md

@@ -325,3 +325,316 @@ MAX_REQUESTS_PER_MINUTE = 80
 // Set the max requests to 80
 MAX_REQUESTS_PER_MINUTE = 80
 ```
+
+## 11. OOP Principles (SOLID)
+
+The SOLID principles guide class and module design toward maintainability. Each principle reduces a specific coupling or fragility problem. Apply them when designing components, services, or modules in any object-oriented or module-oriented language.
+
+### Single Responsibility Principle (SRP)
+
+A class (or module) should have exactly one reason to change. If a change in database schema AND a change in email formatting both require editing the same class, that class has two responsibilities.
+
+**DO:** Split distinct responsibilities into distinct units:
+
+```
+// Separate concerns
+class UserValidator {
+  validate(user) { ... }  // validation logic only
+}
+
+class UserRepository {
+  save(user) { ... }       // persistence logic only
+}
+
+class WelcomeMailer {
+  send(user) { ... }       // email logic only
+}
+```
+
+**DON'T:** Combine unrelated behaviors in a single class:
+
+```
+// God class -- changes for validation, persistence, AND email reasons
+class UserManager {
+  validate(user) { ... }
+  saveToDatabase(user) { ... }
+  sendWelcomeEmail(user) { ... }
+}
+```
+
+### Open/Closed Principle (OCP)
+
+Modules should be open for extension but closed for modification. When requirements change, you should add new code rather than editing existing, tested code.
+
+**DO:** Use polymorphism or strategy pattern to extend behavior:
+
+```
+// Adding a new discount type requires adding a new class, not editing existing ones
+interface DiscountStrategy {
+  calculate(order): number
+}
+
+class SeasonalDiscount implements DiscountStrategy {
+  calculate(order) { return order.total * 0.1 }
+}
+
+class LoyaltyDiscount implements DiscountStrategy {
+  calculate(order) { return order.total * 0.15 }
+}
+
+// New discounts: just add a new class
+class BulkDiscount implements DiscountStrategy {
+  calculate(order) { return order.total * 0.2 }
+}
+```
+
+**DON'T:** Modify existing switch/if chains every time a new variant appears:
+
+```
+// Every new discount type requires editing this function
+function calculateDiscount(order, type) {
+  if (type === "seasonal") return order.total * 0.1
+  if (type === "loyalty") return order.total * 0.15
+  if (type === "bulk") return order.total * 0.2  // must edit to add
+}
+```
+
+### Liskov Substitution Principle (LSP)
+
+Any subtype must be usable wherever its base type is expected, without breaking correctness. If substituting a subclass causes surprising behavior, the hierarchy is wrong.
+
+**DO:** Ensure subclass contracts honor parent contracts:
+
+```
+class Shape {
+  area(): number { ... }
+}
+
+class Rectangle extends Shape {
+  constructor(width, height) { ... }
+  area() { return this.width * this.height }
+}
+
+class Circle extends Shape {
+  constructor(radius) { ... }
+  area() { return Math.PI * this.radius ** 2 }
+}
+
+// Any Shape works correctly in calculateTotal
+function calculateTotal(shapes: Shape[]) {
+  return shapes.reduce((sum, s) => sum + s.area(), 0)
+}
+```
+
+**DON'T:** Create subclasses that violate parent expectations:
+
+```
+// Square extends Rectangle but breaks setWidth/setHeight contract
+class Square extends Rectangle {
+  setWidth(w) {
+    this.width = w
+    this.height = w  // surprise: setting width also changes height
+  }
+}
+// Code expecting Rectangle behavior gets wrong area calculations
+```
+
+### Interface Segregation Principle (ISP)
+
+Clients should not be forced to depend on methods they do not use. Many small, focused interfaces are better than one large, general-purpose interface.
+
+**DO:** Split interfaces by client needs:
+
+```
+interface Readable {
+  read(): string
+}
+
+interface Writable {
+  write(data: string): void
+}
+
+interface Closable {
+  close(): void
+}
+
+// Compose only what each consumer needs
+class FileReader implements Readable, Closable {
+  read() { ... }
+  close() { ... }
+}
+```
+
+**DON'T:** Force implementors to provide methods they don't need:
+
+```
+interface IFileHandler {
+  read(): string
+  write(data: string): void
+  delete(): void
+  rename(name: string): void
+  compress(): void
+  encrypt(): void
+  // Every implementor must handle all 6 methods
+}
+```
+
+### Dependency Inversion Principle (DIP)
+
+High-level modules should depend on abstractions, not on low-level implementation details. Business logic should never directly instantiate infrastructure.
+
+**DO:** Inject abstractions through constructors:
+
+```
+interface UserStore {
+  findById(id: string): User
+}
+
+class UserService {
+  constructor(private store: UserStore) {}
+
+  getUser(id: string) {
+    return this.store.findById(id)
+  }
+}
+
+// Inject at composition root
+const service = new UserService(new PostgresUserStore(db))
+// For testing:
+const testService = new UserService(new InMemoryUserStore())
+```
+
+**DON'T:** Hard-code dependencies inside business logic:
+
+```
+class UserService {
+  getUser(id: string) {
+    // Tightly coupled to PostgreSQL -- cannot test without a database
+    const db = new PostgresDatabase("connection-string")
+    return db.query("SELECT * FROM users WHERE id = ?", [id])
+  }
+}
+```
+
+## 12. Composition and Architecture
+
+Patterns for structuring systems at the module and application level. These complement SOLID by addressing how components connect and how dependencies flow.
+
+### Composition over Inheritance
+
+Prefer composing behaviors via delegation and interfaces over deep inheritance hierarchies. Inheritance creates tight coupling -- a change to the parent ripples through all children.
+
+**DO:** Compose behaviors via delegation:
+
+```
+class EmailNotifier {
+  notify(user, message) { ... }
+}
+
+class SlackNotifier {
+  notify(user, message) { ... }
+}
+
+class OrderService {
+  constructor(private notifiers: Notifier[]) {}
+
+  placeOrder(order) {
+    // ... business logic
+    for (const n of this.notifiers) {
+      n.notify(order.user, "Order placed")
+    }
+  }
+}
+```
+
+**DON'T:** Build deep inheritance chains:
+
+```
+// Fragile hierarchy -- 3+ levels of inheritance
+class Animal { ... }
+class Mammal extends Animal { ... }
+class Dog extends Mammal { ... }
+class GuideDog extends Dog { ... }
+// Change to Animal breaks everything down the chain
+```
+
+**Rule of thumb:** If your inheritance tree exceeds 2 levels, refactor to composition.
+
+### Dependency Injection
+
+Pass dependencies through constructors rather than reaching into global singletons or static service locators. This makes dependencies explicit, testable, and swappable.
+
+**DO:** Declare dependencies in the constructor:
+
+```
+class ReportGenerator {
+  constructor(
+    private dataSource: DataSource,
+    private formatter: Formatter,
+    private logger: Logger,
+  ) {}
+
+  generate(query) {
+    const data = this.dataSource.fetch(query)
+    this.logger.info("Generating report", { query })
+    return this.formatter.format(data)
+  }
+}
+```
+
+**DON'T:** Use static service locators or hidden globals:
+
+```
+class ReportGenerator {
+  generate(query) {
+    // Hidden dependencies -- caller has no idea what this needs
+    const data = ServiceLocator.get(DataSource).fetch(query)
+    const formatted = ServiceLocator.get(Formatter).format(data)
+    GlobalLogger.info("Done")
+    return formatted
+  }
+}
+```
+
+### Clean Architecture Layers
+
+Organize code in concentric layers where dependencies always point inward. Inner layers know nothing about outer layers.
+
+**DO:** Structure as Domain -> Application -> Infrastructure:
+
+```
+// Domain layer (innermost): entities and business rules
+// No imports from Application or Infrastructure
+class Order {
+  calculateTotal() { return this.items.reduce((s, i) => s + i.price, 0) }
+  canBeCancelled() { return this.status === "pending" }
+}
+
+// Application layer: use cases that orchestrate domain objects
+// Imports from Domain only
+class PlaceOrderUseCase {
+  constructor(private orderRepo: OrderRepository) {}
+  execute(items) { ... }
+}
+
+// Infrastructure layer (outermost): databases, HTTP, frameworks
+// Imports from Application and Domain
+class PostgresOrderRepository implements OrderRepository {
+  save(order) { ... }
+}
+```
+
+**DON'T:** Let infrastructure leak into domain logic:
+
+```
+// Domain entity importing from infrastructure -- inverted dependency
+import { prisma } from "../db/client"
+
+class Order {
+  async save() {
+    await prisma.order.create({ data: this })  // infrastructure in domain
+  }
+}
+```
+
+**Layer rule:** Domain has zero external imports. Application imports Domain. Infrastructure imports both but neither imports Infrastructure.