opencode-skills-collection 3.0.46 → 3.0.47

package/bundled-skills/ecl-harness-engineer/agents/creator-docs.md

@@ -0,0 +1,201 @@
+# Documentation Creation Agent
+
+You are creating or updating harness documentation files for a codebase.
+
+## Input
+
+You will receive:
+- Architecture analysis data (from `harness/.analysis/architecture.json`)
+- Audit data showing what exists and what's missing (from `harness/.analysis/audit.json`)
+- Delta list of files to create/update
+
+## Files You May Create/Update
+
+### AGENTS.md
+
+The project entry map for AI agents. This is the most important file. It must help a
+new agent understand the target project first, then explain the harness workflow.
+
+**Target**: 80-120 lines. This is a map, not a manual.
+
+**Structure**:
+```
+Line 1-15:   Project snapshot: what it is, who uses it, core workflow, runtime shape
+Line 16-35:  Core workflow/domain model: real product or system concepts
+Line 36-55:  Where to work: task-to-source map with actual directories/modules
+Line 56-75:  Context loading: AGENTS.md, docs/ECL.md, active change if present, otherwise auto-evolve pending reminder if present, otherwise STATUS, then task-specific project docs
+Line 76-95:  Development + verification commands
+Line 96-120: Safety boundaries and generated harness notes
+```
+
+**Rules**:
+- The first screen must be project-first, not harness-first. It should answer:
+  "What does this project do?", "What is the main user/system workflow?", and
+  "Where would an agent start for common changes?"
+- Extract project identity from `README.md`, entry points, route files, schemas/models,
+  package manifests, and key source directories. Do not infer only from harness files.
+- Include real product/domain concepts when they exist: workflows, entities, API resources,
+  user-facing modules, jobs, commands, or data models.
+- Harness/ECL belongs in context-loading or development-discipline sections. It must not
+  dominate Quick Start or replace project knowledge.
+- Project identity and ECL constraints must not compete: keep the first screen project-first,
+  but make context loading preserve ECL priority. The order must be `AGENTS.md`,
+  `docs/ECL.md`, active change files when present, otherwise read `harness/evolution/pending.md`
+  as a maintenance reminder when it exists, otherwise `docs/STATUS.md`, then README/architecture/design/reference docs.
+- State that active change constraints are the current task source of truth and override
+  generic project guidance and `docs/STATUS.md` for that task.
+- State that `docs/STATUS.md` is a soft handoff file used only when no active change exists.
+  It should point to recent archive context, but it must not trigger default full-archive loading.
+- State that `harness/evolution/pending.md`, when present and no active change exists, should be
+  read before ordinary STATUS resume work as pending maintenance. Reading it does not start
+  auto-evolve, must not block ordinary user work, and should not cause full-archive loading. Codex
+  should ask whether to handle the pending maintenance now unless the user already prioritized the
+  current task.
+- Historical archive loading must be selective: start from `docs/STATUS.md` paths or
+  `harness/changes/INDEX.json`, read archived `summary.md` first, and read spec/plan/tasks/reviews
+  only for debugging, review, or explicit resume work.
+- Never write skill-internal boundaries into the target project. Do not add sections or
+  sentences that describe this skill's own execution limits as if they were project rules.
+- Safety boundaries must be project-level: secrets, generated outputs, uploads, unrelated
+  user edits, migrations, and verification discipline. Agents may modify business code when
+  the user's task requires it.
+- Every link must point to a doc that actually exists
+- Include real package names from architecture analysis
+- Don't embed detailed explanations — link to docs/
+- Link to `docs/ECL.md` for the change lifecycle and context loading protocol
+- Mention `harness/changes/active/` as the current task context, not as a manual
+- Keep only a short change trigger in AGENTS.md; put the detailed lifecycle in `docs/ECL.md`.
+  Typical triggers: APIs, database schema, architecture, permissions, cross-module behavior,
+  multi-file changes, or other non-trivial work.
+
+### docs/ECL.md
+
+The project operating manual for Evolution Constraint Language (ECL).
+
+**Must include**:
+- When to create a change and when small fixes can skip it
+- Small Change vs Structured Change: small low-risk edits may skip active changes; structured work
+  uses active change files and review gates
+- A compact decision tree: existing active change wins; obvious copy/comment/README/local single-file
+  fixes are Small; APIs/data/permissions/architecture/multi-module/runtime/unclear work is
+  Structured; unclear impact requires read-only investigation before deciding
+- Intake Review: support requirement-first and plan-first inputs, ask at most three high-impact
+  questions per round, and record assumptions or `[NEEDS CLARIFICATION: ...]` in `spec.md`
+- Plan-first completeness rule: a complete user plan that does not conflict with repository evidence
+  should not trigger a repeated interview; conflicts or missing acceptance/security/data/compatibility
+  details return to Intake Review
+- Single-active lifecycle: `active/`, `parking/`, `archive/`
+- Stage-boundary update protocol for `summary.md`, `spec.md`, `plan.md`, `tasks.md`, and `reviews/`
+- Spec/plan separation: `spec.md` is WHAT/WHY, `plan.md` is HOW and planning-discovered spec gaps
+- Plan review gate: do not enter implementation until `summary.md` records `plan_review: approved` or `reviews/` contains an equivalent approved plan review
+- Context load order: AGENTS.md, ECL, active change, relevant docs, generated INDEX.json, selected history
+- Auto-evolve handling: `harness-change close/reindex` may generate `harness/evolution/pending.md`;
+  pending is a maintenance reminder, not a hard lock; Codex should ask whether to handle it when no
+  active change exists
+- Auto-evolve independent review boundary: generated scripts create pending context only and do not
+  spawn subagents; the Codex run handling pending evolution requests independent review when
+  available; user approval to handle pending implies permission to request auditor/subagent review
+  when available, and if the environment still requires explicit authorization Codex asks once
+  before falling back to `eval_mode=dry_run` and no auto-apply
+- Auto-evolve completion rule: once Codex starts pending evolution by creating/using an
+  `auto-evolve-harness-*` change, writing a proposal/result, or editing Harness files from pending
+  evidence, it must finish with proposal + `results.tsv` + `harness-evolve mark-complete`; otherwise
+  park/block instead of closing completed
+- Auto-evolve evidence freshness: before processing pending, rebuild `INDEX.json` and use the
+  current eligible archive window; old Candidate Archives are a trigger snapshot only
+- Failure feedback: failed tests/lints become constraints, tasks, or regression notes
+- Script commands: `harness-change new/status/validate/park/resume/close/search/context/reindex` and `harness-evolve check/collect/mark-complete`
+- Rule that `harness/changes/INDEX.json` is generated by scripts and must not be hand-edited
+
+Use `references/ecl-harness.md` for the default text and templates.
+
+### docs/STATUS.md
+
+The lightweight handoff summary for current project state. Create it when adding or updating ECL.
+
+**Target**: 40-80 lines. This is a resume map, not a changelog.
+
+**Must include**:
+- A first-line warning that active change files override this file when present
+- Current active work or "none"
+- Last completed change path, normally the archived `summary.md`
+- Next recommended work
+- Known residual risks or blockers
+- Latest quality gate state
+- Context resume instructions that point to `docs/ECL.md`, active change, `docs/STATUS.md`, and selected archive summaries
+- Auto-evolve pending status when `harness/evolution/pending.md` exists
+
+**Rules**:
+- Update `docs/STATUS.md` before closing an active change with completed work, validation,
+  risks, and next step.
+- After `harness-change close`, update it again with the final archive path.
+- If `harness/evolution/pending.md` exists after close and no active task is present, mention it as
+  pending maintenance and ask whether to handle it now unless the user task is already prioritized;
+  do not treat read-only context loading or asking as started auto-evolve.
+- Do not let CI or hooks auto-write STATUS; they may only validate it.
+- Never treat STATUS as more authoritative than `harness/changes/active/`.
+- Do not store full history in STATUS; keep formal history in `harness/changes/archive/`
+  and discover it through `harness/changes/INDEX.json`.
+
+### docs/ARCHITECTURE.md
+
+The authoritative architecture document.
+
+**Must include**:
+- Mermaid diagram generated from actual import analysis (not templates)
+- Layer table with real packages and their dependencies
+- Source citations (`> Sources: [file:line]()`) for every claim
+- Forbidden dependency rules
+
+### docs/DEVELOPMENT.md
+
+Development setup and commands.
+
+**Must include**:
+- Prerequisites (Go version, Node version, etc.)
+- Build commands that actually work
+- Test commands with explanation
+- Lint commands
+- Harness commands: `verify-harness`, `lint-ecl`, `lint-encoding`, `harness-change`
+
+### docs/design-docs/
+
+Component-level design documents.
+
+**For each key component** (from architecture analysis):
+1. `docs/design-docs/index.md` — Index table
+2. `docs/design-docs/{component}.md` — Detailed design doc
+
+**Each design doc must have**:
+- Overview
+- Architecture (with Mermaid diagram)
+- Key Interfaces (with file:line citations)
+- Execution Flow
+- Error Handling
+
+**Use templates from** `references/documentation-templates.md`.
+
+### Additional docs (as needed)
+
+- `docs/QUALITY.md` — Quality standards
+- `docs/TESTING.md` — Testing strategy
+- `docs/SECURITY.md` — Security considerations
+- `docs/PRODUCT_SENSE.md` — Product context
+- `docs/references/index.md` — Reference index
+
+## Quality Requirements
+
+| Requirement | What This Means |
+|-------------|-----------------|
+| **Source-grounded** | Every claim cites actual file:line |
+| **Real data** | Layer maps use actual packages, not placeholders |
+| **Working commands** | DEVELOPMENT.md commands actually run |
+| **No placeholders** | No "TODO: fill in later" |
+| **Numbered sections** | For stable cross-references |
+| **Generated index clarity** | Docs say INDEX.json is script-generated, not hand-maintained |
+
+## What NOT to Create
+
+- Source code files
+- Test files for business logic
+- Application entry points

package/bundled-skills/ecl-harness-engineer/agents/creator-linters.md

@@ -0,0 +1,123 @@
+# Linter Creation Agent
+
+You are creating or updating linter scripts for agent harness infrastructure.
+
+## Input
+
+You will receive:
+- Architecture analysis with full layer hierarchy (from `harness/.analysis/architecture.json`)
+- Existing linter state (from `harness/.analysis/audit.json`)
+- Delta list of what to create/update
+
+## Files You Create/Update
+
+### scripts/lint-deps.{ext}
+
+**Purpose**: Enforce layer boundaries — prevent forbidden imports.
+
+**Must include**:
+- Complete layer map with EVERY package from the architecture analysis
+- No blind spots — if a package exists, it must be in the layer map
+- Layer rules: Layer N can only import from layers < N
+
+**Error message format** (agent-actionable):
+
+```
+{file}:{line} imports {forbidden_package} (layer {N} → layer {M}).
+Layer {N} packages can only import from layers < {N}.
+
+Fix options:
+1. Move {logic description} to a higher layer (e.g., {suggestion})
+2. Pass the value as a parameter instead of importing directly
+3. Define an interface in layer {N} and implement in layer {M}
+```
+
+This is the most important quality requirement. An error message that only says "Forbidden import" is useless to an agent. The message must tell WHAT is wrong, WHY it matters, and HOW to fix it.
+
+### scripts/lint-quality.{ext}
+
+**Purpose**: Enforce code quality patterns.
+
+**Common rules** (customize based on codebase patterns):
+- File size limits (e.g., > 500 lines → warning)
+- Structured logging enforcement
+- Error wrapping convention
+- Naming conventions
+- Test file presence
+
+**Same error message quality**: WHAT + WHY + HOW.
+
+### scripts/lint-ecl.{ps1|sh|mjs|py}
+
+**Purpose**: Enforce ECL change lifecycle integrity.
+
+**Must check**:
+- `harness/changes/active/` has `summary.md`, `spec.md`, `plan.md`, `tasks.md`, and `reviews/` when active exists.
+- Markdown front matter status is internally consistent.
+- Active changes in `implement`, `validate`, or `done` phase have no high-impact
+  `[NEEDS CLARIFICATION: ...]` markers in `spec.md`.
+- Active changes cannot enter implementation until `plan_review` is approved in `summary.md` or an
+  equivalent approved Plan Review exists in `reviews/review.md`.
+- Executable task lines in `tasks.md` use `T###` ids, and implementation tasks include target paths
+  plus validation notes.
+- `completed` changes have validation results.
+- `tasks.md` with unexplained pending items cannot be completed.
+- `docs/STATUS.md` exists for ECL-enabled projects and clearly says active change files override it.
+- A temporary regenerated index matches `harness/changes/INDEX.json`; otherwise fail and tell the user to run the generated `scripts/harness-change.* reindex` equivalent.
+- `scripts/harness-evolve.*` and `harness/evolution/state.json` exist for core auto-evolve threshold checking.
+- If `harness/evolution/pending.md` exists, lint may report it as pending context, but must not apply or delete it automatically.
+
+### scripts/lint-encoding.{ps1|sh|mjs|py}
+
+**Purpose**: Enforce UTF-8 and prevent mojibake from being written into source or docs.
+
+**Must check**:
+- Scan text files for known mojibake markers listed in `references/ecl-harness.md`.
+- Exclude generated/vendor/cache directories.
+- Return actionable file and line messages.
+
+## Language-Specific Templates
+
+Use templates from `references/linter-templates.md` as starting points, then customize:
+
+- **Go**: Go script that parses imports, checks against layer map
+- **TypeScript/Node.js**: read `references/adapters/typescript.md` first; generate Node/TS-native scripts such as `scripts/lint-deps.mjs` and `scripts/lint-quality.mjs`, and wire them through npm/package-manager scripts
+- **Python**: Python script that parses from/import statements
+- **ECL/Encoding**: use the selected command surface profile from `references/ecl-harness.md` (`.ps1`, `.sh`, `.mjs`, or `.py`)
+
+## Critical Rules
+
+1. **Day-one pass required**: The linter MUST pass on the current codebase without errors. If the codebase has existing violations, document them in `docs/exec-plans/tech-debt-tracker.md` instead of failing the linter.
+
+2. **Complete coverage**: Every package in the codebase must appear in the layer map. Missing packages = blind spots = undetected violations.
+
+3. **Executable**: Scripts must run from the project root. Bash/Node/Python scripts should be executable when the environment supports file modes; Windows-only profiles may use explicit interpreter commands.
+
+4. **Makefile integration**: Ensure `make lint-arch` target runs these scripts.
+
+5. **Generated index, evolution, and handoff discipline**: `lint-ecl` verifies `INDEX.json` freshness, auto-evolve state presence, and `docs/STATUS.md` presence, but never rewrites those files. Rewriting belongs to the generated `harness-change reindex`, `harness-evolve check/mark-complete`, and explicit agent/human handoff updates.
+
+6. **Command surface consistency**: Select the script profile automatically from project evidence. If the project rejects `.ps1`, do not generate PowerShell as the only entrypoint. For Windows projects using Bash, document Git Bash, WSL, MSYS2, or CI Linux shell as a prerequisite. If the PowerShell profile is selected, scripts must run on Windows PowerShell 5.1 as well as PowerShell 7.
+
+7. **Strict business gates**: Do not remove or weaken existing project `lint`, `typecheck`, `test`,
+   or `build` checks to make CI pass. If those checks fail before harness creation, report them as
+   pre-existing project debt; keep the generated CI strict unless the user explicitly asks for staged rollout.
+
+## Verification
+
+After creating linters, verify:
+
+```bash
+# Linters are executable
+chmod +x scripts/lint-deps* scripts/lint-quality*
+
+# Linters pass on current codebase
+make lint-arch
+
+# ECL and encoding checks pass
+{ecl_lint_command}
+{encoding_lint_command}
+
+# Count covered packages vs total packages
+# (should be 100%)
+```

package/bundled-skills/ecl-harness-engineer/references/adapters/adapter-schema.md

@@ -0,0 +1,204 @@
+# Language Adapter Schema
+
+Every language adapter must follow this schema. Adapters are the single source of truth
+for all language-specific behavior across the harness system.
+
+## Design Principles
+
+1. **Discover, don't assume**: Adapters define detection rules, not the core system
+2. **One adapter, one language**: Each adapter is self-contained for one language ecosystem
+3. **Graceful degradation**: Every field is optional — missing fields fall back to generic behavior
+4. **Extensibility**: Adding a new language = adding one adapter file, zero core changes
+
+## Schema Definition
+
+```yaml
+adapter:
+  # ─── Metadata ───────────────────────────────────────────────
+  language: string               # Unique identifier: go, typescript, python, java, rust, etc.
+  display_name: string           # Human-readable: "Go", "TypeScript", "Python", etc.
+  version: string                # Adapter schema version (currently "1.0")
+
+  # ─── Detection ──────────────────────────────────────────────
+  # How to identify this language in a project.
+  # Detection runs in order; first match with highest confidence wins.
+  detection:
+    # Files whose existence signals this language (ANY match = candidate)
+    files: [string]
+    # Optional: require file content patterns for higher confidence
+    content_patterns:
+      - file: string             # Glob pattern (e.g., "*.toml", "package.json")
+        pattern: string          # Regex to match inside the file
+    # Overall confidence when detection.files match (0.0 - 1.0)
+    confidence: float
+
+  # ─── Commands ───────────────────────────────────────────────
+  # Standard development commands. null = not applicable for this language.
+  # These are defaults; project-level overrides in DEVELOPMENT.md or
+  # harness/config/validate.json always take priority.
+  commands:
+    build: string | null         # Compile/transpile: "go build ./...", "npm run build"
+    test: string | null          # Run tests: "go test ./...", "npm test"
+    lint: string | null          # General linting: "golangci-lint run", "npm run lint"
+    lint_arch: string | null     # Architectural linting: "make lint-arch", "npm run lint:arch"
+    format: string | null        # Code formatting: "gofmt -w .", "prettier --write ."
+    start: string | null         # Start the application: "go run main.go", "npm start"
+    dev: string | null           # Development mode: "air", "npm run dev"
+
+  # ─── Package Manager ────────────────────────────────────────
+  # How to detect and use the package manager.
+  package_manager:
+    # Detection priority: first match wins
+    detection:
+      - lockfile: string         # e.g., "pnpm-lock.yaml"
+        manager: string          # e.g., "pnpm"
+      - lockfile: string
+        manager: string
+    default: string              # Fallback if no lockfile: "npm", "pip", etc.
+    install_command: string      # Template: "{manager} install"
+
+  # ─── Route Detection ────────────────────────────────────────
+  # How to find HTTP routes, CLI commands, and other entry points.
+  # Used by verify.py and generate_task_verification.py.
+  route_detection:
+    # Indicators that this project is a server (scan file contents)
+    server_indicators:
+      - pattern: string          # Regex to find in source files
+        description: string      # Human-readable explanation
+        frameworks: [string]     # Associated frameworks: ["chi", "gin"]
+
+    # Indicators that this project is a CLI tool
+    cli_indicators:
+      - pattern: string
+        description: string
+        frameworks: [string]
+
+    # Indicators that this project is a frontend app
+    frontend_indicators:
+      - pattern: string
+        description: string
+        frameworks: [string]
+
+    # Route/command extraction patterns
+    patterns:
+      - type: route              # "route" for HTTP, "command" for CLI
+        regex: string            # Extraction regex with named groups
+        groups: [string]         # Named groups: [method, path] or [command_name]
+        frameworks: [string]     # Which frameworks this pattern matches
+
+  # ─── Import Analysis ────────────────────────────────────────
+  # How to analyze imports for dependency linting.
+  import_analysis:
+    # Command to list all packages/modules
+    list_packages: string | null # "go list ./...", null for languages without this
+    # Regex to extract imports from source files
+    import_pattern: string       # e.g., '"([^"]+)"' for Go, 'from [\'"]([^\'"]+)' for TS
+    # File extensions to scan
+    source_extensions: [string]  # [".go"], [".ts", ".tsx", ".js", ".jsx"]
+    # Module root detection
+    module_root_file: string     # "go.mod", "package.json", "pyproject.toml"
+
+  # ─── Layer Conventions ──────────────────────────────────────
+  # Default layer hierarchy for architectural linting.
+  # These are starting-point defaults; the analyzer agent adjusts based on
+  # actual import graph analysis.
+  layer_conventions:
+    patterns:
+      - layer: int               # 0 = foundational, higher = more application-specific
+        paths: [string]          # Directory patterns: ["internal/types", "types", "domain"]
+        description: string      # "Pure types, zero internal imports"
+
+  # ─── Dependency Detection ───────────────────────────────────
+  # How to detect external dependencies (databases, services, etc.)
+  # from the project's dependency manifest.
+  dependency_detection:
+    manifest_file: string        # "go.mod", "package.json", "requirements.txt"
+    # Patterns to detect specific dependency types
+    databases:
+      - pattern: string          # Regex on dependency name
+        type: string             # "postgres", "mysql", "mongodb", "redis", "sqlite"
+        default_port: int
+    services:
+      - pattern: string
+        type: string             # "kafka", "rabbitmq", "elasticsearch", etc.
+        default_port: int
+    # Environment variable detection in source code
+    env_var_patterns:
+      - pattern: string          # e.g., 'os\.Getenv\("([^"]+)"\)' for Go
+
+  # ─── Linter Template ────────────────────────────────────────
+  # Reference to the linter implementation for this language.
+  linter:
+    # Pointer to the section in linter-templates.md
+    template_section: string     # "go-linter", "typescript-linter", etc.
+    # File extension for the linter script
+    script_extension: string     # ".go", ".ts", ".py"
+    # How to run the linter
+    run_command: string          # "go run scripts/lint-deps.go", "npx ts-node scripts/lint-deps.ts"
+
+  # ─── Naming Conventions ─────────────────────────────────────
+  # File and directory naming rules for verify_action.py.
+  naming:
+    file_pattern: string         # Regex: "^[a-z][a-z0-9_]*\\.go$"
+    test_pattern: string         # Regex: "^[a-z][a-z0-9_]*_test\\.go$"
+    directory_style: string      # "snake_case", "kebab-case", "camelCase"
+
+  # ─── CI Template ────────────────────────────────────────────
+  # CI configuration template for this language.
+  ci:
+    # GitHub Actions template (primary)
+    github_actions:
+      image: string              # "golang:1.22", "node:20", "python:3.12"
+      setup_steps: [string]      # Additional setup steps
+      cache_paths: [string]      # Paths to cache: ["~/go/pkg/mod"], ["node_modules"]
+    # Other CI systems can be added here
+```
+
+## Resolution Priority
+
+When the harness system needs language-specific behavior, it follows this resolution chain:
+
+1. **Project-level override** — `harness/config/validate.json`, `DEVELOPMENT.md` commands
+2. **Adapter defaults** — The matching adapter's `commands` section
+3. **Generic fallback** — `generic.md` adapter (discovers from Makefile/README)
+
+## Adding a New Language
+
+To add support for a new language (e.g., Kotlin):
+
+1. Create `references/adapters/kotlin.md` following this schema
+2. Fill in detection rules, commands, route patterns
+3. Optionally add a linter template section to `linter-templates.md`
+4. No changes to core scripts needed — `detect_adapter.py` auto-discovers adapters
+
+## Adapter File Format
+
+Each adapter file uses YAML front matter followed by prose documentation:
+
+```markdown
+---
+adapter:
+  language: kotlin
+  display_name: "Kotlin"
+  version: "1.0"
+  detection:
+    files: [build.gradle.kts, build.gradle]
+    confidence: 0.9
+  commands:
+    build: "./gradlew build"
+    test: "./gradlew test"
+    # ...
+---
+
+# Kotlin Adapter
+
+## Framework-Specific Notes
+
+### Ktor (server)
+- Routes defined via `routing { get("/path") { ... } }`
+- ...
+
+### Spring Boot
+- Routes via `@GetMapping`, `@PostMapping` annotations
+- ...
+```

package/bundled-skills/ecl-harness-engineer/references/adapters/generic.md

@@ -0,0 +1,156 @@
+---
+adapter:
+  language: generic
+  display_name: "Generic (Auto-Discovery)"
+  version: "1.0"
+
+  detection:
+    files: []  # Always matches as fallback
+    confidence: 0.10
+
+  commands:
+    build: null   # Discovered from Makefile / README
+    test: null    # Discovered from Makefile / README
+    lint: null
+    lint_arch: null
+    format: null
+    start: null
+    dev: null
+
+  package_manager:
+    detection: []
+    default: null
+    install_command: null
+
+  route_detection:
+    server_indicators:
+      - pattern: 'listen|serve|http|server'
+        description: "Generic HTTP server indicator"
+        frameworks: []
+    cli_indicators:
+      - pattern: 'argv|args|argparse|getopt|flag'
+        description: "Generic CLI argument parsing"
+        frameworks: []
+    frontend_indicators:
+      - pattern: 'index\\.html|<!DOCTYPE html>'
+        description: "HTML file presence"
+        frameworks: []
+    patterns: []
+
+  import_analysis:
+    list_packages: null
+    import_pattern: null
+    source_extensions: []
+    module_root_file: null
+
+  layer_conventions:
+    patterns:
+      - layer: 0
+        paths: ["types", "models", "domain", "entities"]
+        description: "Core types (generic convention)"
+      - layer: 1
+        paths: ["utils", "lib", "common", "helpers", "shared"]
+        description: "Shared utilities (generic convention)"
+      - layer: 2
+        paths: ["services", "core", "business", "logic"]
+        description: "Business logic (generic convention)"
+      - layer: 3
+        paths: ["handlers", "controllers", "api", "routes", "endpoints"]
+        description: "API layer (generic convention)"
+      - layer: 4
+        paths: ["main", "cmd", "bin", "app", "src/index", "src/main"]
+        description: "Entry points (generic convention)"
+
+  dependency_detection:
+    manifest_file: null
+    databases: []
+    services: []
+    env_var_patterns: []
+
+  linter:
+    template_section: null
+    script_extension: null
+    run_command: null
+
+  naming:
+    file_pattern: null
+    test_pattern: null
+    directory_style: null
+
+  ci:
+    github_actions:
+      image: "ubuntu-latest"
+      setup_steps: []
+      cache_paths: []
+---
+
+# Generic Adapter (Auto-Discovery Fallback)
+
+This adapter activates when no language-specific adapter matches. Instead of
+assuming a specific language (previous behavior: defaulting to Go), it discovers
+commands from project conventions.
+
+## Discovery Strategy
+
+### 1. Makefile Discovery
+
+If a `Makefile` exists, parse targets:
+
+```bash
+# Extract make targets
+grep -E '^[a-zA-Z_-]+:' Makefile | sed 's/:.*//'
+```
+
+Common target mappings:
+| Target Pattern | Mapped Command |
+|---------------|---------------|
+| `build`, `compile` | `commands.build` |
+| `test`, `check` | `commands.test` |
+| `lint`, `lint-arch` | `commands.lint`, `commands.lint_arch` |
+| `fmt`, `format` | `commands.format` |
+| `run`, `start`, `serve` | `commands.start` |
+| `dev`, `watch` | `commands.dev` |
+
+### 2. README Discovery
+
+If no Makefile, scan `README.md` for code blocks with common commands:
+
+```bash
+# Look for fenced code blocks with build/test commands
+grep -A 2 '```' README.md
+```
+
+### 3. package.json Scripts Discovery (non-Node projects)
+
+Some non-Node projects use `package.json` for script aliases:
+
+```bash
+# Check if package.json scripts exist
+cat package.json | python3 -c "import sys,json; [print(k,v) for k,v in json.load(sys.stdin).get('scripts',{}).items()]"
+```
+
+### 4. docker-compose.yml Discovery
+
+If `docker-compose.yml` exists, extract service definitions for environment setup.
+
+## When Generic Adapter Activates
+
+The generic adapter is the **last resort**. It activates only when:
+1. No `go.mod`, `package.json`, `pyproject.toml`, `pom.xml`, `Cargo.toml` exists
+2. Or when the user explicitly requests generic mode
+
+## Behavior Differences from Language-Specific Adapters
+
+| Aspect | Language Adapter | Generic Adapter |
+|--------|-----------------|-----------------|
+| Build command | Hardcoded default | Discovered from Makefile/README |
+| Route detection | Framework-specific regex | Generic HTTP patterns only |
+| Layer conventions | Language-idiomatic paths | Common directory names |
+| Linter | Language-specific template | None (rely on existing tools) |
+| CI template | Language-specific image | Ubuntu with custom steps |
+
+## Extending to New Languages
+
+If you find yourself repeatedly using the generic adapter for a specific language,
+that's a signal to create a proper language adapter. See `adapter-schema.md` for
+the schema to follow.