devflow-kit 1.8.2 → 2.0.0

package/shared/skills/go/references/violations.md

@@ -1,205 +0,0 @@
-# Go Violation Examples
-
-Extended violation patterns for Go reviews. Reference from main SKILL.md.
-
-## Error Handling Violations
-
-### Ignored Errors
-
-```go
-// VIOLATION: Silently discarding error
-data, _ := json.Marshal(user)
-w.Write(data)
-
-// VIOLATION: Error ignored in deferred call
-defer file.Close() // Close() returns error
-
-// VIOLATION: Swallowing error with log
-if err != nil {
-    log.Println("something failed") // Error details lost
-    return nil
-}
-```
-
-### Unwrapped Errors
-
-```go
-// VIOLATION: No context on error
-func LoadConfig(path string) (*Config, error) {
-    data, err := os.ReadFile(path)
-    if err != nil {
-        return nil, err // Caller has no idea what failed
-    }
-    var cfg Config
-    if err := json.Unmarshal(data, &cfg); err != nil {
-        return nil, err // Which unmarshal? What file?
-    }
-    return &cfg, nil
-}
-```
-
----
-
-## Goroutine Leak Violations
-
-### Fire-and-Forget Goroutine
-
-```go
-// VIOLATION: No way to stop or wait for this goroutine
-func StartPoller() {
-    go func() {
-        for {
-            poll()
-            time.Sleep(10 * time.Second)
-        }
-    }()
-}
-
-// VIOLATION: Goroutine blocks forever on channel nobody reads
-func process(items []Item) {
-    ch := make(chan Result)
-    for _, item := range items {
-        go func(i Item) {
-            ch <- compute(i) // Blocks if nobody reads
-        }(item)
-    }
-    // Only reads first result - rest leak
-    result := <-ch
-    _ = result
-}
-```
-
-### Missing Context Cancellation
-
-```go
-// VIOLATION: Goroutine ignores context
-func Fetch(ctx context.Context, url string) ([]byte, error) {
-    ch := make(chan []byte, 1)
-    go func() {
-        resp, _ := http.Get(url) // Ignores ctx cancellation
-        body, _ := io.ReadAll(resp.Body)
-        ch <- body
-    }()
-    return <-ch, nil
-}
-```
-
----
-
-## Interface Pollution Violations
-
-### Premature Interface Definition
-
-```go
-// VIOLATION: Interface defined at producer, not consumer
-package user
-
-type UserStore interface { // Only one implementation exists
-    Get(id string) (*User, error)
-    Save(u *User) error
-    Delete(id string) error
-    List() ([]*User, error)
-    Count() (int, error)
-}
-
-type PostgresStore struct{ db *sql.DB }
-
-func (s *PostgresStore) Get(id string) (*User, error) { ... }
-// ... implements all 5 methods
-```
-
-### God Interface
-
-```go
-// VIOLATION: Interface too large - impossible to mock cleanly
-type Service interface {
-    CreateUser(ctx context.Context, u *User) error
-    GetUser(ctx context.Context, id string) (*User, error)
-    UpdateUser(ctx context.Context, u *User) error
-    DeleteUser(ctx context.Context, id string) error
-    ListUsers(ctx context.Context) ([]*User, error)
-    SendEmail(ctx context.Context, to string, body string) error
-    GenerateReport(ctx context.Context) ([]byte, error)
-    ProcessPayment(ctx context.Context, amt int) error
-}
-```
-
----
-
-## Naked Return Violations
-
-```go
-// VIOLATION: Naked returns obscure what's being returned
-func divide(a, b float64) (result float64, err error) {
-    if b == 0 {
-        err = errors.New("division by zero")
-        return // What is result here? Zero - but not obvious
-    }
-    result = a / b
-    return // Have to trace back to find return values
-}
-```
-
----
-
-## init() Abuse Violations
-
-```go
-// VIOLATION: Side effects in init - runs on import
-func init() {
-    db, err := sql.Open("postgres", os.Getenv("DATABASE_URL"))
-    if err != nil {
-        log.Fatal(err) // Crashes on import
-    }
-    globalDB = db
-}
-
-// VIOLATION: Registration magic in init
-func init() {
-    http.HandleFunc("/health", healthCheck) // Hidden route registration
-    prometheus.MustRegister(requestCounter) // Panics if called twice
-}
-```
-
----
-
-## Mutex Violations
-
-```go
-// VIOLATION: Copying mutex (passes by value)
-type Cache struct {
-    mu   sync.Mutex
-    data map[string]string
-}
-
-func process(c Cache) { // c is a COPY - mutex is copied too
-    c.mu.Lock()
-    defer c.mu.Unlock()
-    c.data["key"] = "val"
-}
-
-// VIOLATION: Forgetting to unlock
-func (c *Cache) Get(key string) string {
-    c.mu.Lock()
-    if val, ok := c.data[key]; ok {
-        return val // Mutex never unlocked!
-    }
-    c.mu.Unlock()
-    return ""
-}
-```
-
----
-
-## Slice and Map Violations
-
-```go
-// VIOLATION: Nil map write (runtime panic)
-var m map[string]int
-m["key"] = 1 // panic: assignment to entry in nil map
-
-// VIOLATION: Sharing slice backing array
-func getFirstThree(s []int) []int {
-    return s[:3] // Shares backing array - mutations leak
-}
-```

package/shared/skills/implementation-orchestration/SKILL.md

@@ -1,92 +0,0 @@
----
-name: implementation-orchestration
-description: Agent orchestration for IMPLEMENT intent — pre-flight, Coder, quality gates
-user-invocable: false
-allowed-tools: Read, Grep, Glob, Bash, Task, AskUserQuestion
----
-
-# Implementation Orchestration
-
-Agent pipeline for IMPLEMENT intent in ambient ORCHESTRATED mode. Pre-flight checks, plan synthesis, Coder execution, and quality gates.
-
-This is a lightweight variant of `/implement` for ambient ORCHESTRATED mode. Excluded: strategy selection (single/sequential/parallel Coders), retry loops, PR creation, knowledge loading.
-
-## Iron Law
-
-> **QUALITY GATES ARE NON-NEGOTIABLE**
->
-> Every Coder output passes through Validator → Simplifier → Scrutinizer → re-Validate → Shepherd.
-> Skipping a gate because "it looks fine" is never acceptable. The pipeline runs to completion
-> or halts on failure — there is no shortcut.
-
----
-
-## Phase 1: Pre-flight — Branch Safety
-
-Detect branch type before spawning Coder:
-
-- **Work branches** (`feat/`, `fix/`, `chore/`, `refactor/`, `docs/` prefix): proceed on current branch.
-- **Protected branches** (`main`, `master`, `develop`, `release/*`, `staging`, `production`): ask user via AskUserQuestion with 2-3 suggested branch names following `{type}/{ticket}-{slug}` convention. Include ticket number if available from conversation context.
-- **If user declines branch creation**: proceed on the protected branch. Respect the user's choice.
-
-## Phase 2: Plan Synthesis
-
-Synthesize conversation context into a structured EXECUTION_PLAN for Coder:
-
-- **If a plan exists** in conversation context (from plan mode — accepted in-session or injected after "accept and clear") → use the plan as-is.
-- **Otherwise** → synthesize from conversation: what to build, files/modules affected, constraints, decisions made during discussion.
-
-Format as structured markdown with: Goal, Steps, Files, Constraints, Decisions.
-
-## Phase 3: Coder Execution
-
-Record git SHA before first Coder: `git rev-parse HEAD`
-
-Spawn `Task(subagent_type="Coder")` with input variables:
-- **TASK_ID**: Generated from timestamp (e.g., `task-2026-03-19_1430`)
-- **TASK_DESCRIPTION**: From conversation context
-- **BASE_BRANCH**: Current branch (or newly created branch from Phase 1)
-- **EXECUTION_PLAN**: From Phase 2
-- **PATTERNS**: Codebase patterns from conversation context
-- **CREATE_PR**: `false` (commit only, no push)
-- **DOMAIN**: Inferred from files in scope (`backend`, `frontend`, `tests`, `fullstack`)
-
-**Execution strategy**: Single sequential Coder by default. Parallel Coders only when tasks are self-contained — zero shared contracts, no integration points, different files/modules with no imports between them.
-
-If Coder returns **BLOCKED**, halt the pipeline and report to user.
-
-## Phase 4: FILES_CHANGED Detection
-
-After Coder completes, detect changed files:
-
-```bash
-git diff --name-only {starting_sha}...HEAD
-```
-
-Pass FILES_CHANGED to all quality gate agents.
-
-## Phase 5: Quality Gates
-
-Run sequentially — each gate must pass before the next:
-
-1. `Task(subagent_type="Validator")` (build + typecheck + lint + tests) — retry up to 2× on failure (Coder fixes between retries)
-2. `Task(subagent_type="Simplifier")` — code clarity and maintainability pass on FILES_CHANGED
-3. `Task(subagent_type="Scrutinizer")` — 9-pillar quality evaluation on FILES_CHANGED
-4. `Task(subagent_type="Validator")` (re-validate after Simplifier/Scrutinizer changes)
-5. `Task(subagent_type="Shepherd")` — verify implementation matches original request — retry up to 2× if misalignment found
-
-If any gate exhausts retries, halt pipeline and report what passed and what failed.
-
-## Phase 6: Completion
-
-Report results:
-- Commits created (from Coder)
-- Files changed
-- Quality gate results (pass/fail per gate)
-- No push — user decides when to push
-
-## Error Handling
-
-- **Coder BLOCKED**: Halt immediately, report blocker to user
-- **Validator fails after retries**: Report specific failures, halt pipeline
-- **Shepherd misalignment after retries**: Report misalignment details, let user decide next steps

package/shared/skills/implementation-patterns/SKILL.md

@@ -1,162 +0,0 @@
----
-name: implementation-patterns
-description: This skill should be used when the user asks to "create an API endpoint", "add CRUD operations", "implement event handlers", "set up logging", "add configuration", or builds features involving database operations, REST/GraphQL APIs, pub/sub patterns, or service configuration. Provides implementation patterns that follow existing codebase conventions.
-user-invocable: false
-allowed-tools: Read, Grep, Glob
----
-
-# Implementation Patterns
-
-Reference for common implementation patterns. Use these patterns to write consistent, maintainable code.
-
-## Iron Law
-
-> **FOLLOW EXISTING PATTERNS**
->
-> Match the codebase style, don't invent new conventions. If the project uses Result types,
-> use Result types. If it uses exceptions, use exceptions. Consistency trumps personal
-> preference. The best pattern is the one already in use.
-
-## When This Skill Activates
-
-- Implementing CRUD operations
-- Creating API endpoints
-- Writing event handlers
-- Setting up configuration
-- Adding logging
-- Database operations
-
----
-
-## Pattern Categories
-
-### CRUD Operations
-
-Create, Read, Update, Delete with Result types and proper error handling.
-
-**Core pattern**: Validate -> Transform -> Persist -> Return
-
-```typescript
-async function createUser(input: CreateUserInput): Promise<Result<User, CreateError>> {
-  const validated = validateCreateUser(input);
-  if (!validated.ok) return Err({ type: 'validation', details: validated.error });
-
-  const user: User = { id: generateId(), ...validated.value, createdAt: new Date() };
-  const saved = await userRepository.save(user);
-  if (!saved.ok) return Err({ type: 'persistence', details: saved.error });
-
-  return Ok(saved.value);
-}
-```
-
-### API Endpoints
-
-REST endpoint structure with auth, validation, and error mapping.
-
-**Core pattern**: Parse request -> Validate auth -> Execute -> Format response
-
-```typescript
-export async function handleGetUser(req: Request): Promise<Response> {
-  const id = parsePathParam(req, 'id');
-  if (!id.ok) return errorResponse(400, 'Invalid user ID');
-
-  const auth = await authenticate(req);
-  if (!auth.ok) return errorResponse(401, 'Unauthorized');
-
-  const result = await getUser(id.value);
-  if (!result.ok) return handleError(result.error);
-
-  return jsonResponse(200, result.value);
-}
-```
-
-### Event Handlers
-
-Async event processing with idempotency and error recovery.
-
-**Core pattern**: Validate event -> Process -> Handle errors -> Acknowledge
-
-```typescript
-async function handleUserCreated(event: UserCreatedEvent): Promise<void> {
-  const validated = validateEvent(event);
-  if (!validated.ok) { logger.warn('Invalid event'); return; }
-
-  await sendWelcomeEmail(event.userId);
-  await createDefaultSettings(event.userId);
-  logger.info('Event processed successfully');
-}
-```
-
-### Configuration
-
-Environment config with schema validation and feature flags.
-
-**Core pattern**: Define schema -> Load from env -> Validate -> Export frozen
-
-```typescript
-const ConfigSchema = z.object({
-  PORT: z.coerce.number().default(3000),
-  DATABASE_URL: z.string().url(),
-  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
-});
-
-export const config = Object.freeze(ConfigSchema.parse(process.env));
-```
-
-### Logging
-
-Structured logging with context propagation and operation tracking.
-
-**Core pattern**: Context -> Level -> Message -> Data
-
-```typescript
-const logger = createLogger({ requestId: req.id, userId: user.id });
-logger.info('Processing order', { orderId: order.id, items: order.items.length });
-```
-
----
-
-## Anti-Patterns to Avoid
-
-| Anti-Pattern | Problem | Fix |
-|--------------|---------|-----|
-| God functions | 500-line functions doing everything | Compose small, focused functions |
-| Implicit dependencies | Using global state (`db.query(...)`) | Inject dependencies explicitly |
-| Swallowing errors | Empty catch blocks | Handle or propagate with Result types |
-| Magic values | Unexplained numbers/strings | Extract to named constants |
-
----
-
-## Build Optimization
-
-Production builds must exclude test files, debug artifacts, and sourcemaps.
-
-```json
-// tsconfig.prod.json
-{
-  "exclude": ["**/*.test.ts", "**/*.spec.ts", "**/tests/**"]
-}
-```
-
----
-
-## Implementation Checklist
-
-Before implementing, verify:
-
-- [ ] Using Result types for operations that can fail
-- [ ] Validating input at system boundaries
-- [ ] Logging with context (requestId, userId, operation)
-- [ ] Handling all error cases explicitly
-- [ ] Making operations idempotent where possible
-- [ ] Using transactions for multi-step operations
-- [ ] No hardcoded values (use config)
-- [ ] Following existing codebase patterns
-
----
-
-## Extended References
-
-For full implementation examples:
-- `references/violations.md` - Extended violation examples (CRUD, API, Events, Config, Logging)
-- `references/patterns.md` - Extended correct patterns (CRUD, API, Events, Config, Logging)